@checkstack/ui 1.12.0 → 1.13.0

package/src/components/DynamicForm/DynamicForm.tsx

@@ -5,10 +5,10 @@ import { EmptyState } from "../../index";
 import type { DynamicFormProps } from "./types";
 import {
   extractDefaults,
-  isValueEmpty,
   isFieldHiddenByCondition,
   findSecretEnvSibling,
 } from "./utils";
+import { deriveClientFieldErrors } from "./validation.logic";
 import { FormField } from "./FormField";
 
 /**
@@ -31,11 +31,22 @@ export const DynamicForm: React.FC<DynamicFormProps> = ({
   secretNames,
   acquireTypes,
   acquireResetKey,
+  sdkTypes,
+  sdkTypesResetKey,
   importablePackages,
+  templatePreviewContext,
+  showInlineErrors = false,
+  fieldErrors,
+  keepExistingSecretFields,
 }) => {
   // Track previous validity to avoid redundant callbacks
   const prevValidRef = React.useRef<boolean | undefined>(undefined);
 
+  // Top-level field keys the user has interacted with (touched + blurred).
+  // Client-side inline errors only show for touched fields so the form does
+  // not nag while the user is still filling it in for the first time.
+  const [touched, setTouched] = React.useState<Record<string, boolean>>({});
+
   // Initialize form with default values from schema
   React.useEffect(() => {
     if (!schema || !schema.properties) return;
@@ -50,40 +61,24 @@ export const DynamicForm: React.FC<DynamicFormProps> = ({
     // eslint-disable-next-line react-hooks/exhaustive-deps -- Intentional: runs only on schema change. Including onChange would re-fire on parent re-renders; including value would cause an infinite loop since this effect calls onChange(merged)
   }, [schema]);
 
-  // Compute validity and report changes
+  // Single source of truth for client-side validation: the same per-field
+  // error map drives both the inline messages and the validity boolean
+  // (valid iff the map is empty), so what disables the submit button and
+  // what the user sees can never disagree. Honors keep-existing secrets.
+  const clientErrors = React.useMemo(() => {
+    if (!schema || !schema.properties) return {};
+    return deriveClientFieldErrors({ schema, value, keepExistingSecretFields });
+  }, [schema, value, keepExistingSecretFields]);
+
+  // Report validity changes.
   React.useEffect(() => {
     if (!onValidChange || !schema || !schema.properties) return;
-
-    // Check all required fields (including hidden ones like connectionId)
-    const requiredKeys = schema.required ?? [];
-    let isValid = true;
-
-    for (const key of requiredKeys) {
-      const propSchema = schema.properties[key];
-      if (!propSchema) continue;
-
-      // Skip hidden fields - they are auto-populated
-      if (propSchema["x-hidden"]) continue;
-
-      // Skip conditionally hidden fields - they are not visible
-      if (
-        propSchema["x-hidden-when"] &&
-        isFieldHiddenByCondition(propSchema["x-hidden-when"], value)
-      )
-        continue;
-
-      if (isValueEmpty(value[key], propSchema)) {
-        isValid = false;
-        break;
-      }
-    }
-
-    // Only call onValidChange if validity actually changed
+    const isValid = Object.keys(clientErrors).length === 0;
     if (prevValidRef.current !== isValid) {
       prevValidRef.current = isValid;
       onValidChange(isValid);
     }
-  }, [schema, value, onValidChange]);
+  }, [schema, clientErrors, onValidChange]);
 
   if (
     !schema ||
@@ -122,33 +117,86 @@ export const DynamicForm: React.FC<DynamicFormProps> = ({
           const isRequired = schema.required?.includes(key);
           const label = key.charAt(0).toUpperCase() + key.slice(1);
 
+          // Resolve the inline message for this field. Server-supplied
+          // `fieldErrors` (keyed by exact key or a nested `key.*` path) take
+          // precedence and show whenever present; client errors only show
+          // when inline errors are enabled AND the field has been touched.
+          // Either way the message renders below the field without changing
+          // the field's own markup.
+          const clientError =
+            showInlineErrors && touched[key] ? clientErrors[key] : undefined;
+          const fieldError = resolveFieldError({
+            key,
+            fieldErrors,
+            clientError,
+          });
+
           return (
-            <FormField
-              key={key}
-              // Prefix with 'field-' to prevent DOM clobbering when field names
-              // match native DOM properties (e.g., nodeName, tagName, innerHTML)
-              id={`field-${key}`}
-              label={label}
-              propSchema={propSchema}
-              value={value[key]}
-              isRequired={isRequired}
-              formValues={value}
-              optionsResolvers={optionsResolvers}
-              templateProperties={templateProperties}
-              templateCompletionProvider={templateCompletionProvider}
-              typeDefinitions={typeDefinitions}
-              shellEnvVars={shellEnvVars}
-              starterTemplates={starterTemplates}
-              scriptTestRenderer={scriptTestRenderer}
-              secretNames={secretNames}
-              acquireTypes={acquireTypes}
-              acquireResetKey={acquireResetKey}
-              importablePackages={importablePackages}
-              siblingSecretEnv={rootSecretEnv}
-              onChange={(val) => onChange({ ...value, [key]: val })}
-            />
+            <div key={key} className="space-y-1.5">
+              <FormField
+                // Prefix with 'field-' to prevent DOM clobbering when field
+                // names match native DOM properties (e.g. nodeName, tagName)
+                id={`field-${key}`}
+                label={label}
+                propSchema={propSchema}
+                value={value[key]}
+                isRequired={isRequired}
+                formValues={value}
+                optionsResolvers={optionsResolvers}
+                templateProperties={templateProperties}
+                templateCompletionProvider={templateCompletionProvider}
+                typeDefinitions={typeDefinitions}
+                shellEnvVars={shellEnvVars}
+                starterTemplates={starterTemplates}
+                scriptTestRenderer={scriptTestRenderer}
+                secretNames={secretNames}
+                acquireTypes={acquireTypes}
+                acquireResetKey={acquireResetKey}
+                sdkTypes={sdkTypes}
+                sdkTypesResetKey={sdkTypesResetKey}
+                importablePackages={importablePackages}
+                templatePreviewContext={templatePreviewContext}
+                siblingSecretEnv={rootSecretEnv}
+                onChange={(val) => {
+                  // First interaction marks the field touched so its inline
+                  // required error can appear (covers touched-then-blanked).
+                  if (showInlineErrors && !touched[key]) {
+                    setTouched((prev) => ({ ...prev, [key]: true }));
+                  }
+                  onChange({ ...value, [key]: val });
+                }}
+              />
+              {fieldError && (
+                <p className="text-xs text-destructive">{fieldError}</p>
+              )}
+            </div>
           );
         })}
     </div>
   );
 };
+
+/**
+ * Pick the inline error message to render under a top-level field. Server
+ * errors (`fieldErrors`) win over the client error and may be keyed either
+ * by the exact field key or by a nested path (`key.child`); the first nested
+ * match is surfaced so a sub-field problem still flags its parent field.
+ */
+function resolveFieldError({
+  key,
+  fieldErrors,
+  clientError,
+}: {
+  key: string;
+  fieldErrors: Record<string, string> | undefined;
+  clientError: string | undefined;
+}): string | undefined {
+  if (fieldErrors) {
+    if (fieldErrors[key] !== undefined) return fieldErrors[key];
+    const nestedKey = Object.keys(fieldErrors).find((path) =>
+      path.startsWith(`${key}.`),
+    );
+    if (nestedKey !== undefined) return fieldErrors[nestedKey];
+  }
+  return clientError;
+}

package/src/components/DynamicForm/DynamicOptionsField.tsx

@@ -1,6 +1,5 @@
 import React from "react";
-import { Loader2, ChevronDown } from "lucide-react";
-import { cn } from "../../utils";
+import { ChevronDown } from "lucide-react";
 
 import {
   Input,
@@ -10,7 +9,7 @@ import {
   SelectItem,
   SelectTrigger,
   SelectValue,
-  usePerformance,
+  Spinner,
 } from "../../index";
 
 import type { DynamicOptionsFieldProps, ResolverOption } from "./types";
@@ -35,7 +34,6 @@ export const DynamicOptionsField: React.FC<DynamicOptionsFieldProps> = ({
   optionsResolvers,
   onChange,
 }) => {
-  const { isLowPower } = usePerformance();
   const [options, setOptions] = React.useState<ResolverOption[]>([]);
   const [loading, setLoading] = React.useState(true);
   const [error, setError] = React.useState<string | undefined>();
@@ -46,6 +44,15 @@ export const DynamicOptionsField: React.FC<DynamicOptionsFieldProps> = ({
   const formValuesRef = React.useRef(formValues);
   formValuesRef.current = formValues;
 
+  // Ref the resolvers too. A parent re-render (e.g. typing in ANOTHER field of
+  // the same form) can hand down a new `optionsResolvers` object identity even
+  // though the resolver for THIS field is unchanged. Reading it from a ref keeps
+  // it out of the fetch effect's dependencies, so the field only re-fetches when
+  // its resolver NAME or its declared `x-depends-on` values change - not on
+  // every unrelated keystroke (which made the picker flash + re-fetch).
+  const optionsResolversRef = React.useRef(optionsResolvers);
+  optionsResolversRef.current = optionsResolvers;
+
   // Build dependency values string for useEffect dependency tracking
   // Only includes the specific fields this resolver depends on
   const dependencyValues = React.useMemo(() => {
@@ -54,7 +61,7 @@ export const DynamicOptionsField: React.FC<DynamicOptionsFieldProps> = ({
   }, [dependsOn, formValues]);
 
   React.useEffect(() => {
-    const resolver = optionsResolvers[resolverName];
+    const resolver = optionsResolversRef.current[resolverName];
     if (!resolver) {
       setError(`Resolver "${resolverName}" not found`);
       setLoading(false);
@@ -65,7 +72,8 @@ export const DynamicOptionsField: React.FC<DynamicOptionsFieldProps> = ({
     setLoading(true);
     setError(undefined);
 
-    // Use ref to get current form values without adding to dependencies
+    // Use refs to get the current resolvers + form values without adding them
+    // to the dependencies (see the refs above).
     resolver(formValuesRef.current)
       .then((result) => {
         if (!cancelled) {
@@ -83,8 +91,10 @@ export const DynamicOptionsField: React.FC<DynamicOptionsFieldProps> = ({
     return () => {
       cancelled = true;
     };
-    // Only re-fetch when resolver changes or explicit dependencies change
-  }, [resolverName, optionsResolvers, dependencyValues]);
+    // Only re-fetch when the resolver NAME or this field's declared
+    // `x-depends-on` values change - NOT when an unrelated field re-renders the
+    // form (the resolvers object identity is read via ref above).
+  }, [resolverName, dependencyValues]);
 
   // Filter options based on search query
   const filteredOptions = React.useMemo(() => {
@@ -200,12 +210,7 @@ export const DynamicOptionsField: React.FC<DynamicOptionsFieldProps> = ({
       <div className="relative">
         {loading ? (
           <div className="flex items-center gap-2 h-10 px-3 border rounded-md bg-muted/50">
-            <Loader2
-              className={cn(
-                "h-4 w-4 text-muted-foreground",
-                !isLowPower && "animate-spin",
-              )}
-            />
+            <Spinner size="sm" className="text-muted-foreground" />
             <span className="text-sm text-muted-foreground">
               Loading options...
             </span>

package/src/components/DynamicForm/FormField.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useState } from "react";
 import { Plus, Trash2 } from "lucide-react";
+import { renderTemplatePreview } from "@checkstack/template-engine";
 
 import {
   Input,
@@ -23,6 +24,7 @@ import {
   getCleanDescription,
   NONE_SENTINEL,
   findSecretEnvSibling,
+  nestedChildrenRequired,
 } from "./utils";
 import { DynamicOptionsField } from "./DynamicOptionsField";
 import { JsonField } from "./JsonField";
@@ -49,7 +51,10 @@ export const FormField: React.FC<FormFieldProps> = ({
   secretNames,
   acquireTypes,
   acquireResetKey,
+  sdkTypes,
+  sdkTypesResetKey,
   importablePackages,
+  templatePreviewContext,
   siblingSecretEnv,
   onChange,
 }) => {
@@ -167,29 +172,39 @@ export const FormField: React.FC<FormFieldProps> = ({
     const editorTypes = propSchema["x-editor-types"];
     if (editorTypes && editorTypes.length > 0) {
       return (
-        <MultiTypeEditorField
-          id={id}
-          label={label}
-          description={cleanDesc}
-          value={value as string | undefined}
-          isRequired={isRequired}
-          editorTypes={editorTypes}
-          templateProperties={templateProperties}
-          typeDefinitions={typeDefinitions}
-          shellEnvVars={shellEnvVars}
-          starterTemplates={starterTemplates}
-          scriptTestRenderer={
-            propSchema["x-script-testable"] === true
-              ? scriptTestRenderer
-              : undefined
-          }
-          acquireTypes={acquireTypes}
-          acquireResetKey={acquireResetKey}
-          importablePackages={importablePackages}
-          fieldId={id}
-          siblingSecretEnv={siblingSecretEnv}
-          onChange={onChange as (val: string | undefined) => void}
-        />
+        <div className="space-y-2">
+          <MultiTypeEditorField
+            id={id}
+            label={label}
+            description={cleanDesc}
+            value={value as string | undefined}
+            isRequired={isRequired}
+            editorTypes={editorTypes}
+            templateProperties={templateProperties}
+            typeDefinitions={typeDefinitions}
+            shellEnvVars={shellEnvVars}
+            starterTemplates={starterTemplates}
+            scriptTestRenderer={
+              propSchema["x-script-testable"] === true
+                ? scriptTestRenderer
+                : undefined
+            }
+            acquireTypes={acquireTypes}
+            acquireResetKey={acquireResetKey}
+            sdkTypes={sdkTypes}
+            sdkTypesResetKey={sdkTypesResetKey}
+            importablePackages={importablePackages}
+            fieldId={id}
+            siblingSecretEnv={siblingSecretEnv}
+            onChange={onChange as (val: string | undefined) => void}
+          />
+          {propSchema["x-templatable"] && templatePreviewContext && (
+            <TemplatePreviewLine
+              value={(value as string) || ""}
+              context={templatePreviewContext}
+            />
+          )}
+        </div>
       );
     }
 
@@ -319,6 +334,12 @@ export const FormField: React.FC<FormFieldProps> = ({
             placeholder={placeholder}
           />
         )}
+        {propSchema["x-templatable"] && templatePreviewContext && (
+          <TemplatePreviewLine
+            value={(value as string) || ""}
+            context={templatePreviewContext}
+          />
+        )}
       </div>
     );
   }
@@ -440,6 +461,14 @@ export const FormField: React.FC<FormFieldProps> = ({
       properties: propSchema.properties,
       values: value as Record<string, unknown> | undefined,
     });
+    // An OPTIONAL nested object (e.g. an opt-in spend cap) only marks its
+    // schema-required children with `*` once the operator starts providing the
+    // object; while empty, supplying it is optional. A required object always
+    // marks them. (See nestedChildrenRequired.)
+    const childrenRequired = nestedChildrenRequired({
+      objectRequired: isRequired ?? false,
+      objectValue: value,
+    });
     return (
       <div className="space-y-4 p-4 border rounded-lg bg-muted/30">
         <p className="text-sm font-semibold">{label}</p>
@@ -450,7 +479,7 @@ export const FormField: React.FC<FormFieldProps> = ({
             label={key.charAt(0).toUpperCase() + key.slice(1)}
             propSchema={subSchema}
             value={(value as Record<string, unknown>)?.[key]}
-            isRequired={propSchema.required?.includes(key)}
+            isRequired={childrenRequired && (propSchema.required?.includes(key) ?? false)}
             formValues={formValues}
             optionsResolvers={optionsResolvers}
             templateProperties={templateProperties}
@@ -462,7 +491,10 @@ export const FormField: React.FC<FormFieldProps> = ({
             secretNames={secretNames}
             acquireTypes={acquireTypes}
             acquireResetKey={acquireResetKey}
+            sdkTypes={sdkTypes}
+            sdkTypesResetKey={sdkTypesResetKey}
             importablePackages={importablePackages}
+            templatePreviewContext={templatePreviewContext}
             siblingSecretEnv={nestedSecretEnv}
             onChange={(val) =>
               onChange({ ...(value as Record<string, unknown>), [key]: val })
@@ -580,7 +612,10 @@ export const FormField: React.FC<FormFieldProps> = ({
                   secretNames={secretNames}
                   acquireTypes={acquireTypes}
                   acquireResetKey={acquireResetKey}
+                  sdkTypes={sdkTypes}
+                  sdkTypesResetKey={sdkTypesResetKey}
                   importablePackages={importablePackages}
+                  templatePreviewContext={templatePreviewContext}
                   onChange={(val) => {
                     const next = [...(items as unknown[])];
                     next[index] = val;
@@ -723,7 +758,10 @@ export const FormField: React.FC<FormFieldProps> = ({
                 secretNames={secretNames}
                 acquireTypes={acquireTypes}
                 acquireResetKey={acquireResetKey}
+                sdkTypes={sdkTypes}
+                sdkTypesResetKey={sdkTypesResetKey}
                 importablePackages={importablePackages}
+                templatePreviewContext={templatePreviewContext}
                 siblingSecretEnv={variantSecretEnv}
                 onChange={(val) => onChange({ ...currentValue, [key]: val })}
               />
@@ -735,6 +773,28 @@ export const FormField: React.FC<FormFieldProps> = ({
   return <></>;
 };
 
+/**
+ * Inline preview of a templatable field's rendered output against a sample
+ * context. Shown below `x-templatable` string fields when the owning form
+ * supplies a `templatePreviewContext`. Pure render (no DOM/Monaco), so it
+ * matches the run-time `x-templatable` pass exactly.
+ */
+const TemplatePreviewLine: React.FC<{
+  value: string;
+  context: Record<string, unknown>;
+}> = ({ value, context }) => {
+  if (!value || !value.includes("{{")) return null;
+  const rendered = renderTemplatePreview({ value, context });
+  return (
+    <p className="text-xs text-muted-foreground">
+      Preview:{" "}
+      <span className="font-mono break-all text-foreground">
+        {rendered || "(empty)"}
+      </span>
+    </p>
+  );
+};
+
 /**
  * Shared visibility toggle button for secret fields.
  */

package/src/components/DynamicForm/MultiTypeEditorField.tsx

@@ -5,6 +5,7 @@ import {
   CodeEditor,
   type TemplateProperty,
   type AcquireTypes,
+  type AcquiredTypeFile,
 } from "../CodeEditor";
 import {
   Select,
@@ -76,6 +77,10 @@ export interface MultiTypeEditorFieldProps {
   acquireTypes?: AcquireTypes;
   /** Install identity (lockfile hash); resets acquired types on a new install. */
   acquireResetKey?: string;
+  /** The running release's `@checkstack/sdk` editor bundle (helpers + client). */
+  sdkTypes?: ReadonlyArray<AcquiredTypeFile>;
+  /** Release version; resets the mounted SDK libs on a deployment upgrade. */
+  sdkTypesResetKey?: string;
   /**
    * Importable installed package names (`@types/*`-free), forwarded to the
    * TS/JS `CodeEditor` so the import specifier itself autocompletes.
@@ -113,6 +118,8 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
   scriptTestRenderer,
   acquireTypes,
   acquireResetKey,
+  sdkTypes,
+  sdkTypesResetKey,
   importablePackages,
   fieldId,
   siblingSecretEnv,
@@ -396,6 +403,8 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           typeDefinitions={typeDefinitions}
           acquireTypes={acquireTypes}
           acquireResetKey={acquireResetKey}
+          sdkTypes={sdkTypes}
+          sdkTypesResetKey={sdkTypesResetKey}
           importablePackages={importablePackages}
         />
       )}
@@ -410,6 +419,8 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           typeDefinitions={typeDefinitions}
           acquireTypes={acquireTypes}
           acquireResetKey={acquireResetKey}
+          sdkTypes={sdkTypes}
+          sdkTypesResetKey={sdkTypesResetKey}
           importablePackages={importablePackages}
         />
       )}

package/src/components/DynamicForm/index.ts

@@ -30,3 +30,17 @@ export {
   EDITOR_TYPE_LABELS,
   findSecretEnvSibling,
 } from "./utils";
+
+// Validation logic (pure, DOM-free) for inline field errors and the
+// keep-existing-secret rule. Consumers map server zod issues to fields and
+// strip blank keep-existing secrets before submit.
+export {
+  deriveClientFieldErrors,
+  deriveServerFieldErrors,
+  parseServerValidationData,
+  omitKeepExistingSecrets,
+  listSecretFieldKeys,
+  serverValidationDataSchema,
+  type FieldErrorMap,
+  type ServerValidationData,
+} from "./validation.logic";

package/src/components/DynamicForm/types.ts

@@ -1,5 +1,10 @@
 import type React from "react";
-import type { TemplateProperty, ShellEnvVar, AcquireTypes } from "../CodeEditor";
+import type {
+  TemplateProperty,
+  ShellEnvVar,
+  AcquireTypes,
+  AcquiredTypeFile,
+} from "../CodeEditor";
 import type { TemplateCompletionProvider } from "../TemplateValueInput";
 import type { EditorType } from "@checkstack/common";
 
@@ -12,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.
@@ -30,8 +36,19 @@ export interface JsonSchemaProperty extends JsonSchemaPropertyCore<JsonSchemaPro
   "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
@@ -152,12 +169,53 @@ export interface DynamicFormProps {
   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 */
@@ -178,7 +236,11 @@ export interface FormFieldProps {
   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