@checkstack/ui 1.12.0 → 1.13.0

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,28 @@ 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

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([]);
+  });
+});

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

@@ -0,0 +1,210 @@
+import { z } from "zod";
+
+import type { JsonSchema, JsonSchemaProperty } from "./types";
+import { isValueEmpty, isFieldHiddenByCondition } from "./utils";
+
+/**
+ * A map from a field path to a human-readable validation message. The path
+ * is dot-joined (e.g. `spendCap.tokenBudget`) so it lines up with the keys
+ * DynamicForm renders for nested object fields. The top-level segment is
+ * always the form field DynamicForm shows; nested segments identify the
+ * offending sub-field for the message text.
+ */
+export type FieldErrorMap = Record<string, string>;
+
+/**
+ * Zod schema for a single zod issue as it crosses the oRPC boundary. The
+ * backend attaches the original `ZodError.issues` array to the
+ * `ORPCError.data` payload; oRPC serializes it to JSON and the client
+ * deserializes it, so we re-parse it here rather than trusting its shape.
+ * Only the fields we actually consume are required.
+ */
+const serverZodIssueSchema = z.object({
+  path: z.array(z.union([z.string(), z.number()])),
+  message: z.string(),
+});
+
+/**
+ * Zod schema for the structured validation payload the backend places on
+ * `ORPCError.data` for connection-config validation failures. `code`
+ * discriminates this payload from any other structured error data so we
+ * never mis-map an unrelated error onto form fields.
+ */
+export const serverValidationDataSchema = z.object({
+  code: z.literal("CONFIG_VALIDATION"),
+  issues: z.array(serverZodIssueSchema),
+});
+
+export type ServerValidationData = z.infer<typeof serverValidationDataSchema>;
+
+/**
+ * Parse an unknown error payload (typically `error.data` from an oRPC
+ * `ORPCError`) into the structured connection-config validation shape.
+ * Returns `undefined` when the payload is not structured config-validation
+ * data, signalling the caller to fall back to a toast/banner.
+ */
+export function parseServerValidationData(
+  data: unknown,
+): ServerValidationData | undefined {
+  const result = serverValidationDataSchema.safeParse(data);
+  return result.success ? result.data : undefined;
+}
+
+/**
+ * Map a structured server validation payload onto DynamicForm field paths.
+ *
+ * Each zod issue's `path` is joined with dots to form a field path. Only
+ * issues whose first path segment names a property that actually exists in
+ * the rendered schema are considered "mappable"; everything else (empty
+ * paths, unknown roots) is reported back as `unmapped` so the caller can
+ * surface it via the existing toast/banner instead of silently dropping it.
+ *
+ * When multiple issues target the same path, the first one wins (zod emits
+ * the most specific issue first for a given location).
+ */
+export function deriveServerFieldErrors({
+  issues,
+  schema,
+}: {
+  issues: ServerValidationData["issues"];
+  schema: JsonSchema;
+}): { mapped: FieldErrorMap; unmapped: string[] } {
+  const mapped: FieldErrorMap = {};
+  const unmapped: string[] = [];
+  const properties = schema.properties ?? {};
+
+  for (const issue of issues) {
+    const root = issue.path[0];
+    const rootKey = typeof root === "string" ? root : undefined;
+
+    if (rootKey === undefined || !(rootKey in properties)) {
+      unmapped.push(issue.message);
+      continue;
+    }
+
+    const fieldPath = issue.path.map(String).join(".");
+
+    if (mapped[fieldPath] === undefined) {
+      mapped[fieldPath] = issue.message;
+    }
+  }
+
+  return { mapped, unmapped };
+}
+
+/**
+ * Compute client-side validation problems from the JSON schema and the
+ * current form values. Mirrors the validity computation DynamicForm already
+ * does for `onValidChange`, but returns a per-field message map instead of a
+ * single boolean so the offending fields can be flagged inline. The form is
+ * considered valid exactly when this map is empty, so the same call drives
+ * both the inline errors and the `onValidChange` boolean.
+ *
+ * At minimum this flags empty REQUIRED fields (reusing {@link isValueEmpty}
+ * so the notion of "empty" stays in lock-step). Hidden and
+ * conditionally-hidden required fields are skipped because the user cannot
+ * fill them. Optional empty fields never produce an error.
+ *
+ * `keepExistingSecretFields` lists `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" - the redacted preview never returns the
+ * value, so an empty input is expected and MUST count as valid rather than a
+ * missing-required error. A blank `x-secret` field NOT in this set (create
+ * mode, or a secret that was never set) is still treated as missing-required.
+ */
+export function deriveClientFieldErrors({
+  schema,
+  value,
+  keepExistingSecretFields = [],
+}: {
+  schema: JsonSchema;
+  value: Record<string, unknown>;
+  keepExistingSecretFields?: string[];
+}): FieldErrorMap {
+  const errors: FieldErrorMap = {};
+  const properties = schema.properties;
+  if (!properties) return errors;
+
+  const keepExisting = new Set(keepExistingSecretFields);
+  const requiredKeys = schema.required ?? [];
+
+  for (const key of requiredKeys) {
+    const propSchema: JsonSchemaProperty | undefined = properties[key];
+    if (!propSchema) continue;
+
+    // Hidden fields are auto-populated; the user cannot act on them.
+    if (propSchema["x-hidden"]) continue;
+
+    const hiddenWhen = propSchema["x-hidden-when"];
+    if (hiddenWhen && isFieldHiddenByCondition(hiddenWhen, value)) continue;
+
+    if (!isValueEmpty(value[key], propSchema)) continue;
+
+    // A blank secret that already has a stored value is "keep existing",
+    // not missing-required.
+    if (propSchema["x-secret"] === true && keepExisting.has(key)) continue;
+
+    errors[key] = `${labelForKey(key)} is required.`;
+  }
+
+  return errors;
+}
+
+/**
+ * Strip blank `x-secret` fields that are flagged keep-existing from a config
+ * object before submit, so an empty input does not overwrite (clear) the
+ * stored secret. The update path treats an absent secret key as "leave the
+ * stored value untouched"; sending `""` would clear it. CREATE mode passes an
+ * empty `keepExistingSecretFields`, so nothing is stripped there.
+ */
+export function omitKeepExistingSecrets({
+  schema,
+  value,
+  keepExistingSecretFields,
+}: {
+  schema: JsonSchema;
+  value: Record<string, unknown>;
+  keepExistingSecretFields: string[];
+}): Record<string, unknown> {
+  const properties = schema.properties;
+  if (!properties || keepExistingSecretFields.length === 0) return value;
+
+  const keepExisting = new Set(keepExistingSecretFields);
+  const result: Record<string, unknown> = {};
+
+  for (const [key, fieldValue] of Object.entries(value)) {
+    const propSchema = properties[key];
+    const isBlankKeepExistingSecret =
+      propSchema?.["x-secret"] === true &&
+      keepExisting.has(key) &&
+      isValueEmpty(fieldValue, propSchema);
+    if (isBlankKeepExistingSecret) continue;
+    result[key] = fieldValue;
+  }
+
+  return result;
+}
+
+/**
+ * List the top-level `x-secret` field keys declared in a schema. The owning
+ * page uses this in EDIT mode to mark every secret field as keep-existing
+ * (their stored values are redacted out of the loaded preview, so a blank
+ * input must mean "keep existing" rather than "clear"). CREATE mode passes
+ * an empty list so blank secrets stay genuinely required.
+ */
+export function listSecretFieldKeys(schema: JsonSchema): string[] {
+  const properties = schema.properties;
+  if (!properties) return [];
+  return Object.entries(properties)
+    .filter(([, propSchema]) => propSchema["x-secret"] === true)
+    .map(([key]) => key);
+}
+
+/**
+ * Derive the human-readable label DynamicForm renders for a field key
+ * (capitalized first letter), kept in sync with the label logic in
+ * `DynamicForm.tsx` so inline messages read naturally.
+ */
+function labelForKey(key: string): string {
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}

package/src/components/DynamicIcon.tsx

@@ -1,29 +1,46 @@
-import { icons, type LucideIcon } from "lucide-react";
-import { Settings } from "lucide-react";
-import type { LucideIconName } from "@checkstack/common";
+import { lazy, Suspense } from "react";
+import { Settings, type LucideIcon } from "lucide-react";
+import type { IconName, BrandIconName } from "@checkstack/common";
+import { brandIcons } from "./BrandIcon";
 
-// Re-export the type for convenience
-export type { LucideIconName } from "@checkstack/common";
+// Re-export the icon-name types for convenience.
+export type { IconName, LucideIconName } from "@checkstack/common";
 
 /**
  * Props for the DynamicIcon component
  */
 export interface DynamicIconProps {
-  /** Lucide icon name in PascalCase (e.g., 'AlertCircle', 'HeartPulse') */
-  name?: LucideIconName;
+  /**
+   * Icon name. Lucide names are PascalCase (e.g. 'CircleAlert', 'HeartPulse');
+   * the few brand names lucide v1 dropped ('Github', 'Gitlab') resolve to
+   * vendored marks.
+   */
+  name?: IconName;
   /** CSS class name to apply to the icon */
   className?: string;
   /** Fallback icon if name is not provided */
   fallback?: LucideIcon;
 }
 
+// The lucide icon set is loaded lazily through `iconRegistry` (see that file):
+// importing lucide's `icons` map eagerly would ship the entire ~1600-icon set
+// in the initial bundle. `RegistryIcon` is the only importer of that map, and
+// it's behind React.lazy, so the icon set is fetched on demand the first time a
+// data-driven icon renders - never in the initial load.
+const RegistryIcon = lazy(() => import("./iconRegistry"));
+
+function isBrandIcon(name: string): name is BrandIconName {
+  return Object.prototype.hasOwnProperty.call(brandIcons, name);
+}
+
 /**
- * Dynamically renders a Lucide icon by name.
- * Falls back to Settings icon if the icon name is not provided.
+ * Dynamically renders an icon by name. Lucide icons are code-split into a single
+ * on-demand chunk; vendored brand icons render synchronously. Falls back to the
+ * Settings icon if no name is provided.
  *
  * @example
- * <DynamicIcon name="AlertCircle" />
- * <DynamicIcon name="HeartPulse" className="h-6 w-6" />
+ * <DynamicIcon name="CircleAlert" />
+ * <DynamicIcon name="Github" className="h-6 w-6" />
  */
 export function DynamicIcon({
   name,
@@ -34,12 +51,17 @@ export function DynamicIcon({
     return <FallbackIcon className={className} />;
   }
 
-  const Icon = icons[name];
-
-  // Fallback if icon name doesn't exist in lucide-react
-  if (!Icon) {
-    return <FallbackIcon className={className} />;
+  // Brand marks lucide v1 removed - render the vendored component synchronously.
+  if (isBrandIcon(name)) {
+    const Brand = brandIcons[name];
+    return <Brand className={className} />;
   }
 
-  return <Icon className={className} />;
+  return (
+    // Invisible, correctly-sized placeholder while the icon chunk loads, so
+    // there's no layout shift and no flash of a wrong (fallback) icon.
+    <Suspense fallback={<span aria-hidden className={className} />}>
+      <RegistryIcon name={name} className={className} />
+    </Suspense>
+  );
 }