@checkstack/ui 1.11.0 → 1.13.0

package/src/components/DynamicForm/types.ts

@@ -1,4 +1,10 @@
-import type { TemplateProperty, ShellEnvVar } from "../CodeEditor";
+import type React from "react";
+import type {
+  TemplateProperty,
+  ShellEnvVar,
+  AcquireTypes,
+  AcquiredTypeFile,
+} from "../CodeEditor";
 import type { TemplateCompletionProvider } from "../TemplateValueInput";
 import type { EditorType } from "@checkstack/common";
 
@@ -11,6 +17,7 @@ import type {
   JsonSchemaPropertyCore,
   JsonSchemaBase,
 } from "@checkstack/common";
+import type { FieldErrorMap } from "./validation.logic";
 
 /**
  * JSON Schema property with DynamicForm-specific x-* extensions for config rendering.
@@ -26,8 +33,48 @@ export interface JsonSchemaProperty extends JsonSchemaPropertyCore<JsonSchemaPro
   "x-searchable"?: boolean; // Shows search input for filtering dropdown options
   "x-editor-types"?: EditorType[]; // Available editor types for multi-type input
   "x-hidden-when"?: Record<string, string[]>; // Conditionally hide based on sibling field values
+  "x-duration"?: boolean; // Render a DurationInput (single-unit duration object)
+  "x-script-testable"?: boolean; // Field is an inline script that can be tested in-UI
+  "x-secret-env"?: boolean; // Record field is a secret -> env mapping (SecretEnvEditor)
+  "x-templatable"?: boolean; // String value is rendered through the template engine at run time
 }
 
+/**
+ * Sample context used to preview the rendered output of `x-templatable`
+ * string fields in the editor (e.g. `{ environment: { baseUrl: "..." } }`).
+ * When supplied to DynamicForm, a "Preview" line appears below each
+ * templatable field showing `renderTemplatePreview(value, context)` so authors
+ * see the resolved value while editing. Shares the run-time render semantics
+ * (see `@checkstack/template-engine`), so the preview never diverges.
+ */
+export type TemplatePreviewContext = Record<string, unknown>;
+
+/**
+ * Renders the inline script-test UI beneath a testable script field. The
+ * owning feature page supplies this; it owns the RPC call + sample-context
+ * state and typically renders a `ScriptTestPanel`. The form only decides
+ * *where* it appears (below any `x-script-testable` field whose selected
+ * editor type is a code language). Mirrors the callback-prop pattern used
+ * by `optionsResolvers` / `templateCompletionProvider`.
+ */
+export type ScriptTestRenderer = (args: {
+  /** The field's id (form key). */
+  fieldId: string;
+  /** Editor language currently selected in the field. */
+  kind: "typescript" | "shell";
+  /** Current script source in the field. */
+  script: string;
+  /**
+   * The current value of the SIBLING secret→env mapping field (the field
+   * annotated `x-secret-env` within the same config object as the script),
+   * if any. DynamicForm locates it by the annotation — not by name — so the
+   * test panel can inject `__SECRET_<NAME>__` placeholders (or the operator's
+   * overrides) for the same secrets the real action declares. `undefined`
+   * when the config has no `x-secret-env` field or it's empty.
+   */
+  secretEnv?: Record<string, string>;
+}) => React.ReactNode;
+
 /** Option returned by an options resolver */
 export interface ResolverOption {
   value: string;
@@ -98,6 +145,77 @@ export interface DynamicFormProps {
    * fields with a working example. Keyed by `EditorType`.
    */
   starterTemplates?: EditorStarterTemplates;
+  /**
+   * Optional renderer for the inline script-test panel. When supplied,
+   * fields flagged `x-script-testable` (whose selected editor type is a
+   * code language) render this beneath the editor so operators can run
+   * the script against a sample context. Omit it and no test UI appears.
+   */
+  scriptTestRenderer?: ScriptTestRenderer;
+  /**
+   * Optional list of secret NAMES (never values) for `x-secret-env` record
+   * fields. The owning page fetches these from the secrets plugin's
+   * `listSecretNames` and passes them here so the secret-env editor offers
+   * name autocomplete. Omit it and the editor still works as free text.
+   */
+  secretNames?: string[];
+  /**
+   * Optional lazy type-acquisition resolver forwarded to TS/JS editor-type
+   * fields. When supplied, the editor fetches + registers the `.d.ts` of any
+   * npm package the script imports, so `import { x } from "pkg"`
+   * autocompletes. Injected by the owning page (see
+   * `@checkstack/script-packages-frontend`).
+   */
+  acquireTypes?: AcquireTypes;
+  /** Install identity (lockfile hash); resets acquired types on a new install. */
+  acquireResetKey?: string;
+  /**
+   * The running release's `@checkstack/sdk` editor bundle, forwarded to TS/JS
+   * editors so `import { defineHealthCheck } from "@checkstack/sdk/healthcheck"`
+   * resolves with real, version-matched types.
+   */
+  sdkTypes?: ReadonlyArray<AcquiredTypeFile>;
+  /** Release version; resets the mounted SDK libs on a deployment upgrade. */
+  sdkTypesResetKey?: string;
+  /**
+   * Importable installed package names (already `@types/*`-free), forwarded to
+   * TS/JS editors so the import specifier itself autocompletes
+   * (`import {} from "lod"` -> `lodash`).
+   */
+  importablePackages?: string[];
+  /**
+   * Optional sample context for previewing `x-templatable` fields. When
+   * supplied, a "Preview" line appears below each templatable string field
+   * showing the rendered output against this context (e.g. a sample
+   * environment's custom fields). Omit it and templatable fields render
+   * normally with no preview.
+   */
+  templatePreviewContext?: TemplatePreviewContext;
+  /**
+   * Opt-in. When `true`, the form shows inline per-field validation messages
+   * (for empty required fields) REACTIVELY once a field has been touched and
+   * blurred, so the user can see WHY the submit button is disabled without
+   * the form nagging while they are still typing. Defaults to `false`, so
+   * every existing consumer is visually unchanged unless it opts in.
+   */
+  showInlineErrors?: boolean;
+  /**
+   * Optional externally-supplied per-field error messages, keyed by field
+   * path (dot-joined for nested object fields, e.g. `spendCap.tokenBudget`).
+   * Use this to surface SERVER validation failures inline on the offending
+   * field. These render whenever present, independent of the touched-state
+   * gate. Omit it (the default) and no external errors show.
+   */
+  fieldErrors?: FieldErrorMap;
+  /**
+   * Optional list of `x-secret` field keys whose value is already stored
+   * server-side (EDIT mode). A blank input on such a field means "keep the
+   * existing secret" and is therefore VALID, not missing-required - the
+   * redacted preview never returns the value, so the input is expected to be
+   * empty. CREATE mode omits this (or passes `[]`) so blank required secrets
+   * stay invalid. Drives both the validity boolean and the inline errors.
+   */
+  keepExistingSecretFields?: string[];
 }
 
 /** Props for the FormField component */
@@ -114,6 +232,21 @@ export interface FormFieldProps {
   typeDefinitions?: string;
   shellEnvVars?: ShellEnvVar[];
   starterTemplates?: EditorStarterTemplates;
+  scriptTestRenderer?: ScriptTestRenderer;
+  secretNames?: string[];
+  acquireTypes?: AcquireTypes;
+  acquireResetKey?: string;
+  sdkTypes?: ReadonlyArray<AcquiredTypeFile>;
+  sdkTypesResetKey?: string;
+  importablePackages?: string[];
+  /** Sample context for previewing `x-templatable` fields. */
+  templatePreviewContext?: TemplatePreviewContext;
+  /**
+   * Current value of the sibling `x-secret-env` mapping field within the
+   * SAME config object as this field, located by annotation. Threaded down
+   * so a testable script field can forward it to {@link ScriptTestRenderer}.
+   */
+  siblingSecretEnv?: Record<string, string>;
   /** Callback when value changes. Omit val to clear the field. */
   onChange: (val?: unknown) => void;
 }

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

@@ -5,6 +5,7 @@ import {
   extractDefaults,
   getCleanDescription,
   isValueEmpty,
+  nestedChildrenRequired,
   isFieldHiddenByCondition,
   NONE_SENTINEL,
   parseSelectValue,
@@ -201,6 +202,43 @@ describe("isValueEmpty", () => {
   });
 });
 
+describe("nestedChildrenRequired", () => {
+  it("marks children of a REQUIRED object regardless of value", () => {
+    expect(
+      nestedChildrenRequired({ objectRequired: true, objectValue: undefined }),
+    ).toBe(true);
+    expect(
+      nestedChildrenRequired({ objectRequired: true, objectValue: {} }),
+    ).toBe(true);
+  });
+
+  it("does NOT mark children of an OPTIONAL object that is empty/unset", () => {
+    // The spend-cap case: empty optional object -> no required `*`.
+    expect(
+      nestedChildrenRequired({ objectRequired: false, objectValue: undefined }),
+    ).toBe(false);
+    expect(
+      nestedChildrenRequired({ objectRequired: false, objectValue: {} }),
+    ).toBe(false);
+    expect(
+      nestedChildrenRequired({
+        objectRequired: false,
+        objectValue: { tokenBudget: "", windowMinutes: "" },
+      }),
+    ).toBe(false);
+  });
+
+  it("marks children of an OPTIONAL object once it is being provided", () => {
+    // Operator started filling the cap -> guide completion with `*`.
+    expect(
+      nestedChildrenRequired({
+        objectRequired: false,
+        objectValue: { tokenBudget: 1000, windowMinutes: "" },
+      }),
+    ).toBe(true);
+  });
+});
+
 describe("NONE_SENTINEL", () => {
   it("is a specific string constant", () => {
     expect(NONE_SENTINEL).toBe("__none__");

package/src/components/DynamicForm/utils.ts

@@ -69,6 +69,60 @@ export function isValueEmpty(
   return false;
 }
 
+/**
+ * Whether a nested object's schema-required children should display the
+ * required `*` marker. A REQUIRED nested object always marks its required
+ * children. An OPTIONAL nested object (e.g. an opt-in spend cap) only marks
+ * them once the operator is actually providing the object (any child has a
+ * non-empty value) — while it is empty, supplying it is optional, so its
+ * children must not show `*` (the form is valid without any of them).
+ */
+export function nestedChildrenRequired({
+  objectRequired,
+  objectValue,
+}: {
+  objectRequired: boolean;
+  objectValue: unknown;
+}): boolean {
+  if (objectRequired) return true;
+  if (objectValue === null || typeof objectValue !== "object") return false;
+  return Object.values(objectValue as Record<string, unknown>).some(
+    (entry) => entry !== undefined && entry !== null && entry !== "",
+  );
+}
+
+/**
+ * Locate the value of the secret→env mapping field within an object's
+ * properties by the `x-secret-env` annotation (NOT by a hard-coded field
+ * name), and return it. Used to feed the inline script-test panel the same
+ * `secretEnv` the sibling action declares, so a test injects placeholders /
+ * overrides for those secrets. Returns `undefined` when no `x-secret-env`
+ * field exists or its value isn't a record.
+ */
+export function findSecretEnvSibling({
+  properties,
+  values,
+}: {
+  properties: Record<string, JsonSchemaProperty> | undefined;
+  values: Record<string, unknown> | undefined;
+}): Record<string, string> | undefined {
+  if (!properties || !values) return undefined;
+  for (const [key, propSchema] of Object.entries(properties)) {
+    if (propSchema["x-secret-env"] === true) {
+      const value = values[key];
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        const record: Record<string, string> = {};
+        for (const [k, v] of Object.entries(value)) {
+          if (typeof v === "string") record[k] = v;
+        }
+        return record;
+      }
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
 /** Sentinel value used to represent "None" selection in Select components */
 export const NONE_SENTINEL = "__none__";
 

package/src/components/DynamicForm/validation.logic.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  deriveClientFieldErrors,
+  deriveServerFieldErrors,
+  parseServerValidationData,
+  omitKeepExistingSecrets,
+  listSecretFieldKeys,
+} from "./validation.logic";
+import type { JsonSchema } from "./types";
+
+const connectionSchema: JsonSchema = {
+  type: "object",
+  required: ["apiKey", "baseUrl"],
+  properties: {
+    apiKey: { type: "string", "x-secret": true },
+    baseUrl: { type: "string" },
+    organization: { type: "string" },
+    spendCap: {
+      type: "object",
+      required: ["tokenBudget"],
+      properties: {
+        tokenBudget: { type: "number" },
+      },
+    },
+  },
+};
+
+describe("deriveClientFieldErrors", () => {
+  it("flags empty required fields", () => {
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "", baseUrl: undefined },
+    });
+    expect(errors.apiKey).toBeDefined();
+    expect(errors.baseUrl).toBeDefined();
+    expect(errors.apiKey).toContain("required");
+  });
+
+  it("returns no error for filled required fields", () => {
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "sk-123", baseUrl: "https://api.example.com" },
+    });
+    expect(errors.apiKey).toBeUndefined();
+    expect(errors.baseUrl).toBeUndefined();
+  });
+
+  it("never flags optional empty fields", () => {
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "sk-123", baseUrl: "https://x", organization: "" },
+    });
+    expect(errors.organization).toBeUndefined();
+  });
+
+  it("skips required fields hidden by x-hidden", () => {
+    const schema: JsonSchema = {
+      type: "object",
+      required: ["connectionId"],
+      properties: { connectionId: { type: "string", "x-hidden": true } },
+    };
+    const errors = deriveClientFieldErrors({ schema, value: {} });
+    expect(errors.connectionId).toBeUndefined();
+  });
+
+  it("skips required fields hidden by x-hidden-when", () => {
+    const schema: JsonSchema = {
+      type: "object",
+      required: ["token"],
+      properties: {
+        mode: { type: "string" },
+        token: { type: "string", "x-hidden-when": { mode: ["anonymous"] } },
+      },
+    };
+    const errors = deriveClientFieldErrors({
+      schema,
+      value: { mode: "anonymous" },
+    });
+    expect(errors.token).toBeUndefined();
+  });
+
+  it("flags a required nested object whose required child is empty", () => {
+    const errors = deriveClientFieldErrors({
+      schema: { ...connectionSchema, required: ["spendCap"] },
+      value: { spendCap: {} },
+    });
+    expect(errors.spendCap).toBeDefined();
+  });
+
+  it("returns an empty map for a schema with no properties", () => {
+    const errors = deriveClientFieldErrors({
+      schema: { type: "object" },
+      value: {},
+    });
+    expect(errors).toEqual({});
+  });
+
+  it("edit + blank x-secret + existing secret => valid (no required error)", () => {
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "", baseUrl: "https://api.example.com" },
+      keepExistingSecretFields: ["apiKey"],
+    });
+    expect(errors.apiKey).toBeUndefined();
+    expect(errors.baseUrl).toBeUndefined();
+    expect(Object.keys(errors)).toHaveLength(0);
+  });
+
+  it("create + blank x-secret => required error", () => {
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "", baseUrl: "https://api.example.com" },
+      keepExistingSecretFields: [],
+    });
+    expect(errors.apiKey).toBeDefined();
+  });
+
+  it("edit + blank x-secret + no existing secret for that field => required error", () => {
+    // apiKey was never set, so it is NOT in keepExistingSecretFields.
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "", baseUrl: "https://api.example.com" },
+      keepExistingSecretFields: ["someOtherSecret"],
+    });
+    expect(errors.apiKey).toBeDefined();
+  });
+
+  it("does not exempt a blank NON-secret required field via keepExisting", () => {
+    const errors = deriveClientFieldErrors({
+      schema: connectionSchema,
+      value: { apiKey: "sk-1", baseUrl: "" },
+      keepExistingSecretFields: ["baseUrl"],
+    });
+    // baseUrl is not x-secret, so the keep-existing exemption must not apply.
+    expect(errors.baseUrl).toBeDefined();
+  });
+});
+
+describe("listSecretFieldKeys", () => {
+  it("lists only x-secret field keys", () => {
+    expect(listSecretFieldKeys(connectionSchema)).toEqual(["apiKey"]);
+  });
+
+  it("returns an empty list when there are no secret fields", () => {
+    expect(listSecretFieldKeys({ type: "object", properties: {} })).toEqual([]);
+  });
+});
+
+describe("omitKeepExistingSecrets", () => {
+  it("strips a blank keep-existing secret so it is not sent on submit", () => {
+    const result = omitKeepExistingSecrets({
+      schema: connectionSchema,
+      value: { apiKey: "", baseUrl: "https://x", organization: "acme" },
+      keepExistingSecretFields: ["apiKey"],
+    });
+    expect("apiKey" in result).toBe(false);
+    expect(result.baseUrl).toBe("https://x");
+    expect(result.organization).toBe("acme");
+  });
+
+  it("keeps a freshly-typed secret value", () => {
+    const result = omitKeepExistingSecrets({
+      schema: connectionSchema,
+      value: { apiKey: "sk-new", baseUrl: "https://x" },
+      keepExistingSecretFields: ["apiKey"],
+    });
+    expect(result.apiKey).toBe("sk-new");
+  });
+
+  it("strips nothing on create (empty keep-existing list)", () => {
+    const value = { apiKey: "", baseUrl: "https://x" };
+    const result = omitKeepExistingSecrets({
+      schema: connectionSchema,
+      value,
+      keepExistingSecretFields: [],
+    });
+    expect(result).toEqual(value);
+  });
+});
+
+describe("parseServerValidationData", () => {
+  it("parses a well-formed config-validation payload", () => {
+    const parsed = parseServerValidationData({
+      code: "CONFIG_VALIDATION",
+      issues: [{ path: ["apiKey"], message: "Required" }],
+    });
+    expect(parsed?.issues).toHaveLength(1);
+  });
+
+  it("returns undefined for an unrelated payload", () => {
+    expect(parseServerValidationData(undefined)).toBeUndefined();
+    expect(parseServerValidationData({ code: "OTHER" })).toBeUndefined();
+    expect(parseServerValidationData("boom")).toBeUndefined();
+  });
+});
+
+describe("deriveServerFieldErrors", () => {
+  it("maps issues with a known top-level path", () => {
+    const { mapped, unmapped } = deriveServerFieldErrors({
+      schema: connectionSchema,
+      issues: [{ path: ["apiKey"], message: "API key is invalid" }],
+    });
+    expect(mapped.apiKey).toBe("API key is invalid");
+    expect(unmapped).toHaveLength(0);
+  });
+
+  it("maps nested paths with dot notation", () => {
+    const { mapped } = deriveServerFieldErrors({
+      schema: connectionSchema,
+      issues: [
+        { path: ["spendCap", "tokenBudget"], message: "Must be positive" },
+      ],
+    });
+    expect(mapped["spendCap.tokenBudget"]).toBe("Must be positive");
+  });
+
+  it("falls back unmapped issues whose root is unknown", () => {
+    const { mapped, unmapped } = deriveServerFieldErrors({
+      schema: connectionSchema,
+      issues: [{ path: ["nonexistent"], message: "Surprise" }],
+    });
+    expect(Object.keys(mapped)).toHaveLength(0);
+    expect(unmapped).toEqual(["Surprise"]);
+  });
+
+  it("treats an empty path as unmappable", () => {
+    const { mapped, unmapped } = deriveServerFieldErrors({
+      schema: connectionSchema,
+      issues: [{ path: [], message: "Whole object is wrong" }],
+    });
+    expect(Object.keys(mapped)).toHaveLength(0);
+    expect(unmapped).toEqual(["Whole object is wrong"]);
+  });
+
+  it("keeps the first message when a path repeats", () => {
+    const { mapped } = deriveServerFieldErrors({
+      schema: connectionSchema,
+      issues: [
+        { path: ["apiKey"], message: "First" },
+        { path: ["apiKey"], message: "Second" },
+      ],
+    });
+    expect(mapped.apiKey).toBe("First");
+  });
+
+  it("returns empty maps for no issues", () => {
+    const { mapped, unmapped } = deriveServerFieldErrors({
+      schema: connectionSchema,
+      issues: [],
+    });
+    expect(mapped).toEqual({});
+    expect(unmapped).toEqual([]);
+  });
+});