@checkstack/ui 1.8.3 → 1.10.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/components/ListEmptyState.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { Inbox } from "lucide-react";
+import { EmptyState } from "./EmptyState";
+
+interface ListEmptyStateProps {
+  /**
+   * The name of the resource type the list would display (e.g. `"checks"`,
+   * `"incidents"`). Drives the default `"No {resource} yet"` headline.
+   */
+  resource: string;
+  /**
+   * Optional supplemental description rendered beneath the headline.
+   */
+  description?: React.ReactNode;
+  /**
+   * Optional action area, typically a primary CTA button such as
+   * "Create your first check".
+   */
+  actions?: React.ReactNode;
+  /**
+   * Optional icon override. Defaults to the lucide `Inbox` glyph so callers
+   * don't have to pick one for every list.
+   */
+  icon?: React.ReactNode;
+}
+
+/**
+ * ListEmptyState - the canonical empty state for a list-shaped resource.
+ *
+ * Thin wrapper around {@link EmptyState} that supplies a consistent
+ * "No {resource} yet" headline and a sensible default icon. Use this on
+ * any page that renders a list and may have zero items so the UX stays
+ * uniform across plugins.
+ */
+export const ListEmptyState: React.FC<ListEmptyStateProps> = ({
+  resource,
+  description,
+  actions,
+  icon,
+}) => {
+  const resolvedIcon = icon ?? <Inbox className="h-10 w-10" />;
+
+  return (
+    <EmptyState
+      title={`No ${resource} yet`}
+      description={description}
+      icon={resolvedIcon}
+      actions={actions}
+    />
+  );
+};

package/src/components/QueryErrorState.tsx

@@ -0,0 +1,64 @@
+import React from "react";
+import { AlertCircle } from "lucide-react";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  Alert,
+  AlertContent,
+  AlertDescription,
+  AlertIcon,
+  AlertTitle,
+} from "./Alert";
+import { Button } from "./Button";
+
+interface QueryErrorStateProps {
+  /**
+   * The error captured from a failed query (e.g. TanStack Query's `error`).
+   * Funnelled through {@link extractErrorMessage} so callers don't have to
+   * narrow the type at every call site.
+   */
+  error: unknown;
+  /**
+   * Invoked when the user clicks the "Retry" button. Wire this to the
+   * underlying `refetch()` of the failing query.
+   */
+  onRetry: () => void;
+  /**
+   * Optional resource name to personalise the headline, e.g.
+   * `resource="checks"` -> "Could not load checks".
+   */
+  resource?: string;
+}
+
+/**
+ * QueryErrorState - canonical inline error UI for failed list / detail
+ * queries. Renders an `error`-variant {@link Alert} with the extracted
+ * error message and a Retry button.
+ */
+export const QueryErrorState: React.FC<QueryErrorStateProps> = ({
+  error,
+  onRetry,
+  resource,
+}) => {
+  const message = extractErrorMessage(error);
+  const title = resource ? `Could not load ${resource}` : "Something went wrong";
+
+  return (
+    <Alert variant="error">
+      <AlertIcon>
+        <AlertCircle className="h-4 w-4" />
+      </AlertIcon>
+      <AlertContent>
+        <AlertTitle>{title}</AlertTitle>
+        <AlertDescription>{message}</AlertDescription>
+      </AlertContent>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={onRetry}
+        className="shrink-0"
+      >
+        Retry
+      </Button>
+    </Alert>
+  );
+};

package/src/components/ResponsiveTable.tsx

@@ -0,0 +1,92 @@
+/**
+ * ResponsiveTable - dual-layout primitive for tabular data that must
+ * degrade gracefully on narrow viewports.
+ *
+ * # API decision
+ *
+ * The original plan considered a context-driven `priority` prop on a
+ * special `ResponsiveTableHead` so cells could declare which columns
+ * disappear on mobile. Implementing that without `any` requires either
+ * (a) cloning every `TableCell` child to inject a context-derived
+ * `data-priority` attribute, or (b) maintaining a parallel index of
+ * `TableHead` children to wire their priorities into the cells by
+ * position. Both shapes leak the matching responsibility into the
+ * primitive and produce gnarly typings around the `Table*` re-exports.
+ *
+ * Instead this file ships the simpler, fully type-safe fallback:
+ *
+ *   - `<ResponsiveTable>` - a wrapper that renders its children inside
+ *     the standard {@link Table} layout on `sm` viewports and up, and
+ *     hides them on smaller screens.
+ *   - `<MobileCardList>` - a sibling wrapper consumers render alongside
+ *     the table. It is only visible below `sm`, so callers compose the
+ *     two side-by-side and decide per-row what the mobile presentation
+ *     looks like (typically a stacked card with high-priority fields).
+ *
+ * The two wrappers use Tailwind's `hidden sm:block` / `sm:hidden`
+ * utilities, so they swap purely in CSS - no JS media-query gating, no
+ * SSR/CSR mismatch risk, and consumers keep full control over which
+ * fields surface on mobile.
+ *
+ * Re-export the standard `Table*` primitives from `@checkstack/ui` for
+ * the desktop branch; do NOT use `<table>` markup inside
+ * `<MobileCardList>`.
+ */
+import React from "react";
+import { cn } from "../utils";
+
+interface ResponsiveTableProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The desktop tabular layout. Compose with the existing `Table`,
+   * `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`
+   * primitives.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Desktop branch of the dual-layout pattern. Hidden below the `sm`
+ * breakpoint; render a {@link MobileCardList} alongside it to cover
+ * narrow viewports.
+ */
+export const ResponsiveTable = React.forwardRef<
+  HTMLDivElement,
+  ResponsiveTableProps
+>(({ children, className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("hidden sm:block", className)}
+    {...props}
+  >
+    {children}
+  </div>
+));
+
+ResponsiveTable.displayName = "ResponsiveTable";
+
+interface MobileCardListProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The stacked, card-shaped layout for narrow viewports. One item per
+   * row; consumers decide which fields are surfaced.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Mobile branch of the dual-layout pattern. Visible only below the `sm`
+ * breakpoint. Pairs with {@link ResponsiveTable}.
+ */
+export const MobileCardList = React.forwardRef<
+  HTMLDivElement,
+  MobileCardListProps
+>(({ children, className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex flex-col gap-2 sm:hidden", className)}
+    {...props}
+  >
+    {children}
+  </div>
+));
+
+MobileCardList.displayName = "MobileCardList";

package/src/components/Skeleton.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+import { cn } from "../utils";
+import { usePerformance } from "./PerformanceProvider";
+
+interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Override the default sizing / shape. The component already renders a
+   * muted background; pass dimensions via classes like `h-4 w-32 rounded`.
+   */
+  className?: string;
+}
+
+/**
+ * Skeleton - a pulsing placeholder block for loading states.
+ *
+ * Honours {@link usePerformance}: when `isLowPower` is true the pulse
+ * animation is dropped, leaving a static `bg-muted` block so low-power
+ * devices aren't forced through an infinite animation loop.
+ */
+export const Skeleton = React.forwardRef<HTMLDivElement, SkeletonProps>(
+  ({ className, ...props }, ref) => {
+    const { isLowPower } = usePerformance();
+
+    return (
+      <div
+        ref={ref}
+        aria-hidden="true"
+        className={cn(
+          "rounded-md bg-muted",
+          !isLowPower && "animate-pulse",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+Skeleton.displayName = "Skeleton";