@checkstack/ui 1.9.0 → 1.11.0

package/src/components/CodeEditor/validateJsonTemplate.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "bun:test";
+import { validateJsonTemplate } from "./validateJsonTemplate";
+
+describe("validateJsonTemplate", () => {
+  it("accepts valid JSON", () => {
+    expect(validateJsonTemplate('{"a": 1, "b": "two"}')).toEqual([]);
+  });
+
+  it("accepts empty content", () => {
+    expect(validateJsonTemplate("")).toEqual([]);
+    expect(validateJsonTemplate("  \n ")).toEqual([]);
+  });
+
+  it("accepts a template as a quoted string value", () => {
+    expect(
+      validateJsonTemplate('{"repo": "{{trigger.payload.repository}}"}'),
+    ).toEqual([]);
+  });
+
+  it("accepts a template embedded inside a string", () => {
+    expect(validateJsonTemplate('{"msg": "build {{id}} done"}')).toEqual([]);
+  });
+
+  it("accepts an UNQUOTED template value (e.g. a number)", () => {
+    // This is the case a plain JSON validator would reject.
+    expect(
+      validateJsonTemplate('{"timeout": {{trigger.payload.timeout}}}'),
+    ).toEqual([]);
+  });
+
+  it("accepts a template as an array element", () => {
+    expect(validateJsonTemplate('{"items": [{{count}}, 2]}')).toEqual([]);
+  });
+
+  it("flags a genuine structural error (missing comma)", () => {
+    const diagnostics = validateJsonTemplate('{"a": 1 "b": 2}');
+    expect(diagnostics.length).toBeGreaterThan(0);
+  });
+
+  it("flags an unclosed object", () => {
+    const diagnostics = validateJsonTemplate('{"a": 1');
+    expect(diagnostics.length).toBeGreaterThan(0);
+  });
+
+  it("flags a genuine error even when templates are present, at the right offset", () => {
+    // The `2` is missing its preceding colon; offset must point into the
+    // ORIGINAL text (same-length substitution preserves offsets).
+    const text = '{"a": {{x}}, "b" 2}';
+    const diagnostics = validateJsonTemplate(text);
+    expect(diagnostics.length).toBeGreaterThan(0);
+    // The error should land at/after the `2`, not inside the template.
+    const firstOffset = diagnostics[0]?.offset ?? -1;
+    expect(text.slice(firstOffset, firstOffset + 1)).toBe("2");
+  });
+
+  it("does not let an unclosed `{{` swallow a later template", () => {
+    // `{{` on its own is not a complete template, so substitution leaves it;
+    // the real `{{y}}` value is still substituted and the JSON stays valid.
+    expect(validateJsonTemplate('{"a": "{{", "b": {{y}}}')).toEqual([]);
+  });
+});

package/src/components/CodeEditor/validateJsonTemplate.ts

@@ -0,0 +1,26 @@
+// Template-aware JSON validation. See templateValidation.ts for the approach.
+// The real VS Code JSON service still provides highlighting + completion; only
+// its built-in (raw-text) validation is turned off in favour of this, so `{{ }}`
+// is tolerated in any position (including unquoted, e.g. a numeric value).
+import { parse, printParseErrorCode, type ParseError } from "jsonc-parser";
+import {
+  substituteTemplates,
+  type TemplateDiagnostic,
+} from "./templateValidation";
+
+/** Validate template-bearing JSON. Empty content is allowed (no diagnostics). */
+export const validateJsonTemplate = (
+  text: string,
+): TemplateDiagnostic[] => {
+  const errors: ParseError[] = [];
+  parse(substituteTemplates(text), errors, {
+    allowEmptyContent: true,
+    allowTrailingComma: false,
+    disallowComments: true,
+  });
+  return errors.map((parseError) => ({
+    offset: parseError.offset,
+    length: Math.max(parseError.length, 1),
+    message: `JSON: ${printParseErrorCode(parseError.error)}`,
+  }));
+};

package/src/components/CodeEditor/validateXmlTemplate.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "bun:test";
+import { validateXmlTemplate } from "./validateXmlTemplate";
+
+describe("validateXmlTemplate", () => {
+  it("accepts valid XML", () => {
+    expect(validateXmlTemplate("<root><a>1</a></root>")).toEqual([]);
+  });
+
+  it("accepts empty content", () => {
+    expect(validateXmlTemplate("")).toEqual([]);
+    expect(validateXmlTemplate("  \n ")).toEqual([]);
+  });
+
+  it("accepts a template in element text", () => {
+    expect(
+      validateXmlTemplate("<root><repo>{{trigger.payload.repository}}</repo></root>"),
+    ).toEqual([]);
+  });
+
+  it("accepts a template in a (quoted) attribute value", () => {
+    expect(validateXmlTemplate('<root attr="{{id}}"></root>')).toEqual([]);
+  });
+
+  it("flags a mismatched closing tag", () => {
+    const diagnostics = validateXmlTemplate("<a><b></a>");
+    expect(diagnostics.length).toBeGreaterThan(0);
+    expect(diagnostics[0]?.message).toContain("XML:");
+  });
+
+  it("flags an unclosed tag even with templates present", () => {
+    const diagnostics = validateXmlTemplate("<root><x>{{v}}</root>");
+    expect(diagnostics.length).toBeGreaterThan(0);
+  });
+});

package/src/components/CodeEditor/validateXmlTemplate.ts

@@ -0,0 +1,35 @@
+// Template-aware XML validation. See templateValidation.ts for the approach.
+// There is no @codingame standalone XML language service (only Monarch
+// highlighting), so we use fast-xml-parser's validator after template
+// substitution. The validator reports the FIRST error only, with 1-based
+// line/column, which we convert to an offset/range in the original text.
+import { XMLValidator } from "fast-xml-parser";
+import {
+  lineColumnToOffset,
+  substituteTemplates,
+  type TemplateDiagnostic,
+} from "./templateValidation";
+
+/** Validate template-bearing XML. Empty content is allowed (no diagnostics). */
+export const validateXmlTemplate = (
+  text: string,
+): TemplateDiagnostic[] => {
+  const substituted = substituteTemplates(text);
+  if (substituted.trim() === "") {
+    return [];
+  }
+  const result = XMLValidator.validate(substituted, {
+    allowBooleanAttributes: true,
+  });
+  if (result === true) {
+    return [];
+  }
+  const { msg, line, col } = result.err;
+  return [
+    {
+      offset: lineColumnToOffset({ text: substituted, line, column: col }),
+      length: 1,
+      message: `XML: ${msg}`,
+    },
+  ];
+};

package/src/components/CodeEditor/validateYamlTemplate.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "bun:test";
+import { validateYamlTemplate } from "./validateYamlTemplate";
+
+describe("validateYamlTemplate", () => {
+  it("accepts valid YAML", () => {
+    expect(validateYamlTemplate("a: 1\nb: two\n")).toEqual([]);
+  });
+
+  it("accepts empty content", () => {
+    expect(validateYamlTemplate("")).toEqual([]);
+  });
+
+  it("accepts a template as a quoted string value", () => {
+    expect(validateYamlTemplate('repo: "{{trigger.payload.repository}}"')).toEqual(
+      [],
+    );
+  });
+
+  it("accepts an UNQUOTED template value (e.g. a number)", () => {
+    expect(validateYamlTemplate("timeout: {{trigger.payload.timeout}}")).toEqual(
+      [],
+    );
+  });
+
+  it("accepts a template as a list item", () => {
+    expect(validateYamlTemplate("items:\n  - {{count}}\n  - 2")).toEqual([]);
+  });
+
+  it("flags tabs used as indentation", () => {
+    const diagnostics = validateYamlTemplate("foo:\n\tbar: 1");
+    expect(diagnostics.length).toBeGreaterThan(0);
+    expect(diagnostics[0]?.message).toContain("YAML:");
+  });
+
+  it("flags a genuine structural error (with templates present)", () => {
+    const diagnostics = validateYamlTemplate("a: {{x}}\n  b: 2");
+    expect(diagnostics.length).toBeGreaterThan(0);
+  });
+});

package/src/components/CodeEditor/validateYamlTemplate.ts

@@ -0,0 +1,28 @@
+// Template-aware YAML validation. See templateValidation.ts for the approach.
+// There is no @codingame standalone YAML language service (only Monarch
+// highlighting), so we parse with the `yaml` package after template
+// substitution. YAML is permissive (it often parses `{{ }}` as a flow
+// collection), but substitution gives accurate structural validation and still
+// catches real mistakes (bad indentation, tabs, duplicate keys, ...).
+import { parseDocument } from "yaml";
+import {
+  substituteTemplates,
+  type TemplateDiagnostic,
+} from "./templateValidation";
+
+/** Validate template-bearing YAML. */
+export const validateYamlTemplate = (
+  text: string,
+): TemplateDiagnostic[] => {
+  const doc = parseDocument(substituteTemplates(text), {
+    prettyErrors: false,
+  });
+  return doc.errors.map((error) => {
+    const [start, end] = error.pos;
+    return {
+      offset: start,
+      length: Math.max(end - start, 1),
+      message: `YAML: ${error.message}`,
+    };
+  });
+};

package/src/components/DynamicForm/DynamicForm.tsx

@@ -18,6 +18,7 @@ export const DynamicForm: React.FC<DynamicFormProps> = ({
   onValidChange,
   optionsResolvers,
   templateProperties,
+  templateCompletionProvider,
   typeDefinitions,
   shellEnvVars,
   starterTemplates,
@@ -116,6 +117,7 @@ export const DynamicForm: React.FC<DynamicFormProps> = ({
               formValues={value}
               optionsResolvers={optionsResolvers}
               templateProperties={templateProperties}
+              templateCompletionProvider={templateCompletionProvider}
               typeDefinitions={typeDefinitions}
               shellEnvVars={shellEnvVars}
               starterTemplates={starterTemplates}

package/src/components/DynamicForm/FormField.tsx

@@ -13,6 +13,7 @@ import {
   Textarea,
   Toggle,
   ColorPicker,
+  TemplateValueInput,
 } from "../../index";
 
 import type { FormFieldProps, JsonSchemaProperty } from "./types";
@@ -33,6 +34,7 @@ export const FormField: React.FC<FormFieldProps> = ({
   formValues,
   optionsResolvers,
   templateProperties,
+  templateCompletionProvider,
   typeDefinitions,
   shellEnvVars,
   starterTemplates,
@@ -232,7 +234,14 @@ export const FormField: React.FC<FormFieldProps> = ({
       );
     }
 
-    // Default string input
+    // Default string input. When a completion provider is supplied the
+    // field is templatable (e.g. automation action config), so render a
+    // TemplateValueInput wired to it for `{{ … }}` autocomplete; without
+    // one, keep the bare Input so other DynamicForm consumers are
+    // unaffected.
+    const placeholder = propSchema.default
+      ? `Default: ${String(propSchema.default)}`
+      : "";
     return (
       <div className="space-y-2">
         <div>
@@ -243,14 +252,22 @@ export const FormField: React.FC<FormFieldProps> = ({
             <p className="text-sm text-muted-foreground mt-0.5">{cleanDesc}</p>
           )}
         </div>
-        <Input
-          id={id}
-          value={(value as string) || ""}
-          onChange={(e) => onChange(e.target.value)}
-          placeholder={
-            propSchema.default ? `Default: ${String(propSchema.default)}` : ""
-          }
-        />
+        {templateCompletionProvider ? (
+          <TemplateValueInput
+            id={id}
+            value={(value as string) || ""}
+            onChange={(next) => onChange(next)}
+            placeholder={placeholder}
+            completionProvider={templateCompletionProvider}
+          />
+        ) : (
+          <Input
+            id={id}
+            value={(value as string) || ""}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder={placeholder}
+          />
+        )}
       </div>
     );
   }
@@ -352,6 +369,7 @@ export const FormField: React.FC<FormFieldProps> = ({
             formValues={formValues}
             optionsResolvers={optionsResolvers}
             templateProperties={templateProperties}
+            templateCompletionProvider={templateCompletionProvider}
             typeDefinitions={typeDefinitions}
             shellEnvVars={shellEnvVars}
             starterTemplates={starterTemplates}
@@ -463,6 +481,7 @@ export const FormField: React.FC<FormFieldProps> = ({
                   formValues={formValues}
                   optionsResolvers={optionsResolvers}
                   templateProperties={templateProperties}
+                  templateCompletionProvider={templateCompletionProvider}
                   typeDefinitions={typeDefinitions}
                   shellEnvVars={shellEnvVars}
                   starterTemplates={starterTemplates}
@@ -594,6 +613,7 @@ export const FormField: React.FC<FormFieldProps> = ({
                 formValues={formValues}
                 optionsResolvers={optionsResolvers}
                 templateProperties={templateProperties}
+                templateCompletionProvider={templateCompletionProvider}
                 typeDefinitions={typeDefinitions}
                 shellEnvVars={shellEnvVars}
                 starterTemplates={starterTemplates}

package/src/components/DynamicForm/KeyValueEditor.tsx

@@ -3,6 +3,7 @@ import { Plus, Trash2 } from "lucide-react";
 import { Button } from "../Button";
 import { Input } from "../Input";
 import type { TemplateProperty } from "../CodeEditor";
+import { TemplateValueInput } from "../TemplateValueInput";
 
 export interface KeyValuePair {
   key: string;
@@ -28,24 +29,6 @@ export interface KeyValueEditorProps {
   templateProperties?: TemplateProperty[];
 }
 
-/**
- * Detect if cursor is inside an unclosed {{ template context.
- */
-function detectTemplateContext(text: string, cursorPos: number) {
-  const textBefore = text.slice(0, cursorPos);
-  const lastOpenBrace = textBefore.lastIndexOf("{{");
-  const lastCloseBrace = textBefore.lastIndexOf("}}");
-
-  if (lastOpenBrace !== -1 && lastOpenBrace > lastCloseBrace) {
-    return {
-      isInTemplate: true,
-      query: textBefore.slice(lastOpenBrace + 2),
-      startPos: lastOpenBrace,
-    };
-  }
-  return { isInTemplate: false, query: "", startPos: -1 };
-}
-
 /**
  * A key/value pair editor for form data and similar use cases.
  * Supports adding/removing pairs and optional template autocomplete in values.
@@ -131,7 +114,7 @@ export const KeyValueEditor: React.FC<KeyValueEditorProps> = ({
             className="flex-1 font-mono text-sm"
           />
           <span className="text-muted-foreground">=</span>
-          <TemplateInput
+          <TemplateValueInput
             id={`${id}-value-${index}`}
             value={pair.value}
             onChange={(newValue) => handleValueChange(index, newValue)}
@@ -162,153 +145,3 @@ export const KeyValueEditor: React.FC<KeyValueEditorProps> = ({
     </div>
   );
 };
-
-/**
- * An input with simple template autocomplete support.
- * Shows a dropdown when user types "{{".
- */
-const TemplateInput: React.FC<{
-  id: string;
-  value: string;
-  onChange: (value: string) => void;
-  placeholder?: string;
-  templateProperties?: TemplateProperty[];
-}> = ({ id, value, onChange, placeholder, templateProperties }) => {
-  const inputRef = React.useRef<HTMLInputElement>(null);
-  const [showPopup, setShowPopup] = React.useState(false);
-  const [selectedIndex, setSelectedIndex] = React.useState(0);
-  const [templateContext, setTemplateContext] = React.useState<{
-    query: string;
-    startPos: number;
-  }>({ query: "", startPos: -1 });
-
-  // Filter properties based on query
-  const filteredProperties = React.useMemo(() => {
-    if (!templateProperties) return [];
-    if (!templateContext.query.trim()) return templateProperties;
-    const lowerQuery = templateContext.query.toLowerCase();
-    return templateProperties.filter((prop) =>
-      prop.path.toLowerCase().includes(lowerQuery),
-    );
-  }, [templateProperties, templateContext.query]);
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const newValue = e.target.value;
-    onChange(newValue);
-
-    if (!templateProperties || templateProperties.length === 0) return;
-
-    const cursorPos = e.target.selectionStart ?? newValue.length;
-    const context = detectTemplateContext(newValue, cursorPos);
-
-    if (context.isInTemplate) {
-      setTemplateContext({ query: context.query, startPos: context.startPos });
-      setShowPopup(true);
-      setSelectedIndex(0);
-    } else {
-      setShowPopup(false);
-    }
-  };
-
-  const insertProperty = (prop: TemplateProperty) => {
-    if (templateContext.startPos === -1) return;
-
-    const cursorPos = inputRef.current?.selectionStart ?? value.length;
-    const template = `{{${prop.path}}}`;
-    const newValue =
-      value.slice(0, templateContext.startPos) +
-      template +
-      value.slice(cursorPos);
-
-    onChange(newValue);
-    setShowPopup(false);
-
-    // Restore focus
-    setTimeout(() => {
-      inputRef.current?.focus();
-      const newPos = templateContext.startPos + template.length;
-      inputRef.current?.setSelectionRange(newPos, newPos);
-    }, 0);
-  };
-
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-    if (!showPopup || filteredProperties.length === 0) return;
-
-    switch (e.key) {
-      case "ArrowDown": {
-        e.preventDefault();
-        setSelectedIndex((prev) =>
-          prev < filteredProperties.length - 1 ? prev + 1 : 0,
-        );
-        break;
-      }
-      case "ArrowUp": {
-        e.preventDefault();
-        setSelectedIndex((prev) =>
-          prev > 0 ? prev - 1 : filteredProperties.length - 1,
-        );
-        break;
-      }
-      case "Enter":
-      case "Tab": {
-        e.preventDefault();
-        if (filteredProperties[selectedIndex]) {
-          insertProperty(filteredProperties[selectedIndex]);
-        }
-        break;
-      }
-      case "Escape": {
-        e.preventDefault();
-        setShowPopup(false);
-        break;
-      }
-    }
-  };
-
-  // Close popup on blur
-  const handleBlur = () => {
-    // Delay to allow click on popup item
-    setTimeout(() => setShowPopup(false), 150);
-  };
-
-  return (
-    <div className="relative flex-1">
-      <Input
-        ref={inputRef}
-        id={id}
-        value={value}
-        onChange={handleChange}
-        onKeyDown={handleKeyDown}
-        onBlur={handleBlur}
-        placeholder={placeholder}
-        className="font-mono text-sm"
-      />
-      {showPopup && filteredProperties.length > 0 && (
-        <div className="absolute z-50 top-full left-0 mt-1 w-64 max-h-48 overflow-y-auto rounded-md border border-border bg-popover shadow-lg">
-          <div className="p-1">
-            {filteredProperties.map((prop, index) => (
-              <button
-                key={prop.path}
-                type="button"
-                onMouseDown={(e) => {
-                  e.preventDefault();
-                  insertProperty(prop);
-                }}
-                className={`w-full flex items-center justify-between gap-2 px-2 py-1.5 text-xs rounded-sm text-left hover:bg-accent hover:text-accent-foreground ${
-                  index === selectedIndex
-                    ? "bg-accent text-accent-foreground"
-                    : ""
-                }`}
-              >
-                <code className="font-mono truncate">{prop.path}</code>
-                <span className="text-muted-foreground shrink-0">
-                  {prop.type}
-                </span>
-              </button>
-            ))}
-          </div>
-        </div>
-      )}
-    </div>
-  );
-};

package/src/components/DynamicForm/MultiTypeEditorField.tsx

@@ -336,6 +336,14 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
         />
       )}
 
+      {/*
+        Native-code editors (javascript / typescript / shell) intentionally
+        do NOT receive `templateProperties`: `{{ }}` template syntax is for
+        text/markup fields only. Code fields access run context through
+        their language's native mechanism instead — a typed `context`
+        object (driven by `typeDefinitions`) for TS/JS, and `$`-prefixed
+        env vars (driven by `shellEnvVars`) for shell.
+      */}
       {selectedType === "javascript" && (
         <CodeEditor
           id={id}
@@ -343,7 +351,6 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           onChange={onChange}
           language="javascript"
           minHeight="150px"
-          templateProperties={templateProperties}
           typeDefinitions={typeDefinitions}
         />
       )}
@@ -355,7 +362,6 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           onChange={onChange}
           language="typescript"
           minHeight="150px"
-          templateProperties={templateProperties}
           typeDefinitions={typeDefinitions}
         />
       )}
@@ -367,7 +373,6 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           onChange={onChange}
           language="shell"
           minHeight="150px"
-          templateProperties={templateProperties}
           shellEnvVars={shellEnvVars}
         />
       )}
@@ -417,8 +422,10 @@ const RawEditor: React.FC<{
     if (!templateProperties) return [];
     if (!templateContext.query.trim()) return templateProperties;
     const lowerQuery = templateContext.query.toLowerCase();
-    return templateProperties.filter((prop) =>
-      prop.path.toLowerCase().includes(lowerQuery),
+    return templateProperties.filter(
+      (prop) =>
+        prop.path.toLowerCase().includes(lowerQuery) ||
+        (prop.templateRef?.toLowerCase().includes(lowerQuery) ?? false),
     );
   }, [templateProperties, templateContext.query]);
 
@@ -481,7 +488,7 @@ const RawEditor: React.FC<{
       const textarea = textareaRef.current;
       if (!textarea || templateContext.startPos === -1) return;
 
-      const template = `{{${prop.path}}}`;
+      const template = `{{${prop.templateRef ?? prop.path}}}`;
       const cursorPos = textarea.selectionStart ?? 0;
       const newValue =
         value.slice(0, templateContext.startPos) +
@@ -580,7 +587,9 @@ const RawEditor: React.FC<{
                     : ""
                 }`}
               >
-                <code className="font-mono truncate">{prop.path}</code>
+                <code className="font-mono truncate">
+                  {prop.templateRef ?? prop.path}
+                </code>
                 <span className="text-muted-foreground shrink-0">
                   {prop.type}
                 </span>

package/src/components/DynamicForm/types.ts

@@ -1,4 +1,5 @@
 import type { TemplateProperty, ShellEnvVar } from "../CodeEditor";
+import type { TemplateCompletionProvider } from "../TemplateValueInput";
 import type { EditorType } from "@checkstack/common";
 
 // Re-export types used by multi-type editor
@@ -69,6 +70,15 @@ export interface DynamicFormProps {
    * When provided, fields with x-editor-types get {{ autocomplete suggestions.
    */
   templateProperties?: TemplateProperty[];
+  /**
+   * Optional staged, context-aware completion provider for plain
+   * single-line string fields. When supplied, default string inputs
+   * render a {@link TemplateValueInput} wired to this provider instead
+   * of a bare `Input`, so `{{ … }}` expressions get field / comparator /
+   * value / filter autocomplete (the automation editor passes the
+   * template-mode provider here). Omit it and string fields stay plain.
+   */
+  templateCompletionProvider?: TemplateCompletionProvider;
   /**
    * Optional TypeScript declarations to inject into Monaco for `typescript`
    * or `javascript` editor-type fields. Typically built from a schema via
@@ -100,6 +110,7 @@ export interface FormFieldProps {
   formValues: Record<string, unknown>;
   optionsResolvers?: Record<string, OptionsResolver>;
   templateProperties?: TemplateProperty[];
+  templateCompletionProvider?: TemplateCompletionProvider;
   typeDefinitions?: string;
   shellEnvVars?: ShellEnvVar[];
   starterTemplates?: EditorStarterTemplates;

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}
+    />
+  );
+};