@kopai/ui 0.0.5 → 0.2.0

package/src/index.ts

@@ -0,0 +1,15 @@
+export { default as ObservabilityPage } from "./pages/observability.js";
+export { createCatalog } from "./lib/component-catalog.js";
+export { generatePromptInstructions } from "./lib/generate-prompt-instructions.js";
+export {
+  Renderer,
+  createRendererFromCatalog,
+  type RendererComponentProps,
+  type ComponentRenderProps,
+  type ComponentRenderer,
+} from "./lib/renderer.js";
+export {
+  KopaiSDKProvider,
+  useKopaiSDK,
+  type KopaiClient,
+} from "./providers/kopai-provider.js";

package/src/lib/__snapshots__/generate-prompt-instructions.test.ts.snap

@@ -0,0 +1,33 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`generatePromptInstructions > generates full prompt instructions 1`] = `
+"## Available Components
+
+### Card
+A card container
+
+Props:
+- title: string (required)
+Accepts children: yes
+
+---
+
+### Button
+Clickable button
+
+Props:
+- label: string (required)
+Accepts dataSource: yes
+
+---
+
+## Output Schema
+
+{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"root":{"type":"string","description":"root uiElement key in the elements array"},"elements":{"type":"object","propertyNames":{"type":"string","description":"equal to the element key"},"additionalProperties":{"oneOf":[{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","const":"Card"},"children":{"type":"array","items":{"type":"string"}},"parentKey":{"type":"string"},"dataSource":{"$ref":"#/$defs/DataSource"},"props":{"type":"object","properties":{"title":{"type":"string"}},"required":["title"],"additionalProperties":false}},"required":["key","type","children","parentKey","props"],"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","const":"Button"},"children":{"type":"array","items":{"type":"string"}},"parentKey":{"type":"string"},"dataSource":{"$ref":"#/$defs/DataSource"},"props":{"type":"object","properties":{"label":{"type":"string"}},"required":["label"],"additionalProperties":false}},"required":["key","type","children","parentKey","props"],"additionalProperties":false}]}}},"required":["root","elements"],"additionalProperties":false,"$defs":{"DataSource":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"searchTracesPage"},"params":{"type":"object","properties":{"traceId":{"description":"Unique identifier for a trace. All spans from the same trace share the same trace_id. The ID is a 16-byte array.","type":"string"},"spanId":{"description":"Unique identifier for a span within a trace. The ID is an 8-byte array.","type":"string"},"parentSpanId":{"description":"The span_id of this span's parent span. Empty if this is a root span.","type":"string"},"serviceName":{"description":"Service name from resource attributes (service.name).","type":"string"},"spanName":{"description":"Description of the span's operation. E.g., qualified method name or file name with line number.","type":"string"},"spanKind":{"description":"Type of span (INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER). Used to identify relationships between spans.","type":"string"},"statusCode":{"description":"Status code (UNSET, OK, ERROR).","type":"string"},"scopeName":{"description":"Name denoting the instrumentation scope.","type":"string"},"timestampMin":{"description":"Minimum start time of the span. UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. Expressed as string in JSON.","type":"string"},"timestampMax":{"description":"Maximum start time of the span. UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. Expressed as string in JSON.","type":"string"},"durationMin":{"description":"Minimum duration of the span in nanoseconds (end_time - start_time). Expressed as string in JSON.","type":"string"},"durationMax":{"description":"Maximum duration of the span in nanoseconds (end_time - start_time). Expressed as string in JSON.","type":"string"},"spanAttributes":{"description":"Key/value pairs describing the span.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"resourceAttributes":{"description":"Attributes that describe the resource.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"eventsAttributes":{"description":"Attribute key/value pairs on the event.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"linksAttributes":{"description":"Attribute key/value pairs on the link.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"limit":{"description":"Max items to return. Default determined by datasource.","type":"integer","exclusiveMinimum":0,"maximum":1000},"cursor":{"description":"Opaque cursor from previous response for next page.","type":"string"},"sortOrder":{"description":"Sort by timestamp. ASC = oldest first, DESC = newest first.","type":"string","enum":["ASC","DESC"]}},"additionalProperties":false},"refetchIntervalMs":{"type":"number"}},"required":["method","params"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"searchLogsPage"},"params":{"type":"object","properties":{"traceId":{"description":"Unique identifier for a trace. All logs from the same trace share the same trace_id. The ID is a 16-byte array.","type":"string"},"spanId":{"description":"Unique identifier for a span within a trace. The ID is an 8-byte array.","type":"string"},"serviceName":{"description":"Service name from resource attributes (service.name).","type":"string"},"scopeName":{"description":"Name denoting the instrumentation scope.","type":"string"},"severityText":{"description":"Severity text (also known as log level). Original string representation as known at the source.","type":"string"},"severityNumberMin":{"description":"Minimum severity number (inclusive). Normalized to values described in Log Data Model.","type":"number"},"severityNumberMax":{"description":"Maximum severity number (inclusive). Normalized to values described in Log Data Model.","type":"number"},"bodyContains":{"description":"Filter logs where body contains this substring.","type":"string"},"timestampMin":{"description":"Minimum time when the event occurred. UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. Expressed as string in JSON.","type":"string"},"timestampMax":{"description":"Maximum time when the event occurred. UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970. Expressed as string in JSON.","type":"string"},"logAttributes":{"description":"Additional attributes that describe the specific event occurrence.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"resourceAttributes":{"description":"Attributes that describe the resource.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"scopeAttributes":{"description":"Attributes of the instrumentation scope.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"limit":{"description":"Max items to return. Default determined by datasource.","type":"integer","exclusiveMinimum":0,"maximum":1000},"cursor":{"description":"Opaque cursor from previous response for next page.","type":"string"},"sortOrder":{"description":"Sort by timestamp. ASC = oldest first, DESC = newest first.","type":"string","enum":["ASC","DESC"]}},"additionalProperties":false},"refetchIntervalMs":{"type":"number"}},"required":["method","params"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"searchMetricsPage"},"params":{"type":"object","properties":{"metricType":{"type":"string","enum":["Gauge","Sum","Histogram","ExponentialHistogram","Summary"],"description":"Metric type to query."},"metricName":{"description":"The name of the metric.","type":"string"},"serviceName":{"description":"Service name from resource attributes (service.name).","type":"string"},"scopeName":{"description":"Name denoting the instrumentation scope.","type":"string"},"timeUnixMin":{"description":"Minimum time when the data point was recorded. UNIX Epoch time in nanoseconds. Expressed as string in JSON.","type":"string"},"timeUnixMax":{"description":"Maximum time when the data point was recorded. UNIX Epoch time in nanoseconds. Expressed as string in JSON.","type":"string"},"attributes":{"description":"Key/value pairs that uniquely identify the timeseries.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"resourceAttributes":{"description":"Attributes that describe the resource.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"scopeAttributes":{"description":"Attributes of the instrumentation scope.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"limit":{"description":"Max items to return. Default determined by datasource.","type":"integer","exclusiveMinimum":0,"maximum":1000},"cursor":{"description":"Opaque cursor from previous response for next page.","type":"string"},"sortOrder":{"description":"Sort by timestamp. ASC = oldest first, DESC = newest first.","type":"string","enum":["ASC","DESC"]}},"required":["metricType"],"additionalProperties":false},"refetchIntervalMs":{"type":"number"}},"required":["method","params"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"getTrace"},"params":{"type":"object","properties":{"traceId":{"type":"string"}},"required":["traceId"],"additionalProperties":false},"refetchIntervalMs":{"type":"number"}},"required":["method","params"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"discoverMetrics"},"params":{"type":"object","properties":{},"additionalProperties":false},"refetchIntervalMs":{"type":"number"}},"required":["method"],"additionalProperties":false}]}}}
+
+---
+
+## Example
+
+{"root":"card-1","elements":{"card-1":{"key":"card-1","type":"Card","props":{},"children":["button-1"]},"button-1":{"key":"button-1","type":"Button","props":{},"parentKey":"card-1","dataSource":{"method":"searchTracesPage","params":{"limit":10}}}}}"
+`;

package/src/lib/catalog.ts

@@ -0,0 +1,165 @@
+import { createCatalog } from "./component-catalog.js";
+import { z } from "zod";
+
+export const dashboardCatalog = createCatalog({
+  name: "dashboard",
+  components: {
+    // Layout Components
+    Card: {
+      props: z.object({
+        title: z.string().nullable(),
+        description: z.string().nullable(),
+        padding: z.enum(["sm", "md", "lg"]).nullable(),
+      }),
+      hasChildren: true,
+      description: "A card container with optional title",
+    },
+
+    Grid: {
+      props: z.object({
+        columns: z.number().min(1).max(4).nullable(),
+        gap: z.enum(["sm", "md", "lg"]).nullable(),
+      }),
+      hasChildren: true,
+      description: "Grid layout with configurable columns",
+    },
+
+    Stack: {
+      props: z.object({
+        direction: z.enum(["horizontal", "vertical"]).nullable(),
+        gap: z.enum(["sm", "md", "lg"]).nullable(),
+        align: z.enum(["start", "center", "end", "stretch"]).nullable(),
+      }),
+      hasChildren: true,
+      description: "Flex stack for horizontal or vertical layouts",
+    },
+
+    // Data Display Components
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        valuePath: z.string(),
+        format: z.enum(["number", "currency", "percent"]).nullable(),
+        trend: z.enum(["up", "down", "neutral"]).nullable(),
+        trendValue: z.string().nullable(),
+      }),
+      hasChildren: false,
+      description: "Display a single metric with optional trend indicator",
+    },
+
+    Chart: {
+      props: z.object({
+        type: z.enum(["bar", "line", "pie", "area"]),
+        dataPath: z.string(),
+        title: z.string().nullable(),
+        height: z.number().nullable(),
+      }),
+      hasChildren: false,
+      description: "Display a chart from array data",
+    },
+
+    Table: {
+      props: z.object({
+        dataPath: z.string(),
+        columns: z.array(
+          z.object({
+            key: z.string(),
+            label: z.string(),
+            format: z.enum(["text", "currency", "date", "badge"]).nullable(),
+          })
+        ),
+      }),
+      hasChildren: false,
+      description: "Display tabular data",
+    },
+
+    List: {
+      props: z.object({
+        dataPath: z.string(),
+        emptyMessage: z.string().nullable(),
+      }),
+      hasChildren: true,
+      description: "Render a list from array data",
+    },
+
+    // Interactive Components
+    Button: {
+      props: z.object({
+        label: z.string(),
+        variant: z.enum(["primary", "secondary", "danger", "ghost"]).nullable(),
+        size: z.enum(["sm", "md", "lg"]).nullable(),
+        action: z.string(),
+        disabled: z.boolean().nullable(),
+      }),
+      hasChildren: false,
+      description: "Clickable button with action",
+    },
+
+    DatePicker: {
+      props: z.object({
+        label: z.string().nullable(),
+        bindPath: z.string(),
+        placeholder: z.string().nullable(),
+      }),
+      hasChildren: false,
+      description: "Date picker input",
+    },
+
+    // Typography
+    Heading: {
+      props: z.object({
+        text: z.string(),
+        level: z.enum(["h1", "h2", "h3", "h4"]).nullable(),
+      }),
+      hasChildren: false,
+      description: "Section heading",
+    },
+
+    Text: {
+      props: z.object({
+        content: z.string(),
+        variant: z.enum(["body", "caption", "label"]).nullable(),
+        color: z
+          .enum(["default", "muted", "success", "warning", "danger"])
+          .nullable(),
+      }),
+      hasChildren: false,
+      description: "Text paragraph",
+    },
+
+    // Status Components
+    Badge: {
+      props: z.object({
+        text: z.string(),
+        variant: z
+          .enum(["default", "success", "warning", "danger", "info"])
+          .nullable(),
+      }),
+      hasChildren: false,
+      description: "Small status badge",
+    },
+
+    // Special Components
+    Divider: {
+      props: z.object({
+        label: z.string().nullable(),
+      }),
+      hasChildren: false,
+      description: "Visual divider",
+    },
+
+    Empty: {
+      props: z.object({
+        title: z.string(),
+        description: z.string().nullable(),
+        action: z.string().nullable(),
+        actionLabel: z.string().nullable(),
+      }),
+      hasChildren: false,
+      description: "Empty state placeholder",
+    },
+  },
+});
+
+// Export the component list for the AI prompt
+export const componentList = Object.keys(dashboardCatalog.components);

package/src/lib/component-catalog.test.ts

@@ -0,0 +1,357 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { dataSourceSchema, createCatalog } from "./component-catalog.js";
+import type { CatalogueComponentProps } from "./component-catalog.js";
+
+describe("schemas", () => {
+  it("datasource", () => {
+    expect.assertions(0);
+    type DataSource = z.infer<typeof dataSourceSchema>;
+
+    const _testDataSource1 = {
+      method: "searchTracesPage",
+      params: {
+        // @ts-expect-error - invalid param
+        nonExisting: "",
+      },
+    } satisfies DataSource;
+
+    const _testDataSource2 = {
+      method: "searchTracesPage",
+      params: {
+        cursor: "test",
+        eventsAttributes: {
+          foo: "bar",
+        },
+        limit: 3,
+      },
+    } satisfies DataSource;
+  });
+
+  describe("createCatalog", () => {
+    it("creates uiTreeSchema that validates component props", () => {
+      const catalog = createCatalog({
+        name: "test catalog",
+        components: {
+          TestComponent: {
+            description: "test",
+            hasChildren: false,
+            props: z.object({ isImportant: z.boolean() }),
+          },
+        },
+      });
+
+      // Valid data passes
+      const validResult = catalog.uiTreeSchema.safeParse({
+        root: "test-1",
+        elements: {
+          TestComponent: {
+            key: "test-1",
+            type: "TestComponent",
+            children: [],
+            parentKey: "",
+            props: { isImportant: true },
+          },
+        },
+      });
+      expect(validResult.success).toBe(true);
+
+      // Invalid props fail
+      const invalidResult = catalog.uiTreeSchema.safeParse({
+        root: "test-1",
+        elements: {
+          TestComponent: {
+            key: "test-1",
+            type: "TestComponent",
+            children: [],
+            parentKey: "",
+            props: { isImportant: "not-a-boolean" },
+          },
+        },
+      });
+      expect(invalidResult.success).toBe(false);
+    });
+
+    it("returns components with exact types from config", () => {
+      expect.assertions(0);
+
+      const catalog = createCatalog({
+        name: "test catalog",
+        components: {
+          TestComponent: {
+            description: "test",
+            hasChildren: false,
+            props: z.object({ isImportant: z.boolean() }),
+          },
+        },
+      });
+
+      // Valid: accessing defined component
+      const _validAccess = catalog.components.TestComponent;
+
+      // @ts-expect-error - non-existent component
+      const _invalidAccess = catalog.components.NonExistentComponent;
+
+      // Props type preserved - can infer schema type
+      type Props = z.infer<typeof catalog.components.TestComponent.props>;
+      const _validProps: Props = { isImportant: true };
+      // @ts-expect-error - wrong prop type
+      const _invalidProps: Props = { isImportant: "not-boolean" };
+      // @ts-expect-error - non-existent prop
+      const _missingProps: Props = { nonExistent: true };
+    });
+
+    it("validates multiple components with dataSource", () => {
+      const catalog = createCatalog({
+        name: "multi catalog",
+        components: {
+          Button: {
+            description: "button",
+            hasChildren: false,
+            props: z.object({ label: z.string() }),
+          },
+          Card: {
+            description: "card",
+            hasChildren: true,
+            props: z.object({ title: z.string(), bordered: z.boolean() }),
+          },
+        },
+      });
+
+      expect(catalog.name).toBe("multi catalog");
+
+      // Valid with dataSource
+      const validResult = catalog.uiTreeSchema.safeParse({
+        root: "card-1",
+        elements: {
+          Card: {
+            key: "card-1",
+            type: "Card",
+            children: ["btn-1"],
+            parentKey: "",
+            props: { title: "Hello", bordered: true },
+            dataSource: {
+              method: "searchTracesPage",
+              params: { limit: 10 },
+            },
+          },
+          Button: {
+            key: "btn-1",
+            type: "Button",
+            children: [],
+            parentKey: "card-1",
+            props: { label: "Click" },
+          },
+        },
+      });
+      expect(validResult.success).toBe(true);
+
+      // Invalid dataSource params
+      const invalidDataSource = catalog.uiTreeSchema.safeParse({
+        root: "btn-1",
+        elements: {
+          Button: {
+            key: "btn-1",
+            type: "Button",
+            children: [],
+            parentKey: "",
+            props: { label: "Click" },
+            dataSource: {
+              method: "searchTracesPage",
+              params: { limit: null },
+            },
+          },
+        },
+      });
+      expect(invalidDataSource.success).toBe(false);
+    });
+
+    it("types multiple components correctly", () => {
+      expect.assertions(0);
+
+      const catalog = createCatalog({
+        name: "multi catalog",
+        components: {
+          Button: {
+            description: "button",
+            hasChildren: false,
+            props: z.object({ label: z.string() }),
+          },
+          Card: {
+            description: "card",
+            hasChildren: true,
+            props: z.object({ title: z.string() }),
+          },
+        },
+      });
+
+      // Both components accessible
+      const _button = catalog.components.Button;
+      const _card = catalog.components.Card;
+
+      // @ts-expect-error - non-existent
+      const _missing = catalog.components.Missing;
+
+      // Props types preserved per component
+      type ButtonProps = z.infer<typeof catalog.components.Button.props>;
+      type CardProps = z.infer<typeof catalog.components.Card.props>;
+
+      const _validButton: ButtonProps = { label: "hi" };
+      const _validCard: CardProps = { title: "hi" };
+
+      // @ts-expect-error - wrong component props
+      const _wrongButton: ButtonProps = { title: "hi" };
+      // @ts-expect-error - wrong component props
+      const _wrongCard: CardProps = { label: "hi" };
+    });
+
+    it("types uiTreeSchema elements with dataSource", () => {
+      expect.assertions(0);
+
+      const _catalog = createCatalog({
+        name: "test catalog",
+        components: {
+          Button: {
+            description: "button",
+            hasChildren: false,
+            props: z.object({ label: z.string() }),
+          },
+          Card: {
+            description: "card",
+            hasChildren: true,
+            props: z.object({ title: z.string() }),
+          },
+        },
+      });
+
+      type UiTree = z.infer<typeof _catalog.uiTreeSchema>;
+
+      // Valid: elements with dataSource
+      const _validTree: UiTree = {
+        root: "card-1",
+        elements: {
+          "card-1": {
+            key: "card-1",
+            type: "Card",
+            children: ["btn-1"],
+            parentKey: "",
+            props: { title: "Hello" },
+            dataSource: {
+              method: "searchTracesPage",
+              params: { limit: 10 },
+            },
+          },
+          "btn-1": {
+            key: "btn-1",
+            type: "Button",
+            children: [],
+            parentKey: "card-1",
+            props: { label: "Click" },
+          },
+        },
+      };
+
+      const _invalidType: UiTree = {
+        root: "x",
+        elements: {
+          "random-1": {
+            key: "random-1",
+            // @ts-expect-error - non-existent type
+            type: "NonExistant",
+            children: [],
+            parentKey: "",
+            // @ts-expect-error - props don't match any valid type
+            props: {},
+          },
+        },
+      };
+
+      const _invalidProps: UiTree = {
+        root: "btn-1",
+        elements: {
+          Button: {
+            key: "btn-1",
+            type: "Button",
+            children: [],
+            parentKey: "",
+            // @ts-expect-error - wrong props type for element
+            props: { title: "wrong prop" },
+          },
+        },
+      };
+
+      const _invalidDataSource: UiTree = {
+        root: "btn-1",
+        elements: {
+          Button: {
+            key: "btn-1",
+            type: "Button",
+            children: [],
+            parentKey: "",
+            props: { label: "Click" },
+            dataSource: {
+              // @ts-expect-error - invalid dataSource method
+              method: "invalidMethod",
+              params: {},
+            },
+          },
+        },
+      };
+
+      const _invalidDataSourceParams: UiTree = {
+        root: "btn-1",
+        elements: {
+          Button: {
+            key: "btn-1",
+            type: "Button",
+            children: [],
+            parentKey: "",
+            props: { label: "Click" },
+            dataSource: {
+              method: "searchTracesPage",
+              // @ts-expect-error - invalid params for searchTracesPage
+              params: { foo: 1 },
+            },
+          },
+        },
+      };
+    });
+
+    it("types CatalogueComponentProps based on hasChildren", () => {
+      expect.assertions(0);
+
+      type WithChildren = {
+        hasChildren: true;
+        description: string;
+        props: { title: string };
+      };
+      type NoChildren = {
+        hasChildren: false;
+        description: string;
+        props: { label: string };
+      };
+
+      // hasChildren: true -> includes children prop
+      type PropsWithChildren = CatalogueComponentProps<WithChildren>;
+      const _validWithChildren: PropsWithChildren = {
+        element: { props: { title: "hi" } },
+        children: null,
+      };
+      // @ts-expect-error - missing children
+      const _missingChildren: PropsWithChildren = {
+        element: { props: { title: "hi" } },
+      };
+
+      // hasChildren: false -> no children prop
+      type PropsNoChildren = CatalogueComponentProps<NoChildren>;
+      const _validNoChildren: PropsNoChildren = {
+        element: { props: { label: "hi" } },
+      };
+      const _extraChildren: PropsNoChildren = {
+        element: { props: { label: "hi" } },
+        // @ts-expect-error - children not allowed
+        children: null,
+      };
+    });
+  });
+});