🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
docs: Add design-system component relationship chart (#17608)
Ben Bachem2dff8645594d
diff --git a/knip.jsonc b/knip.jsoncindex d7624fcd05..96f3722edc 100644--- a/knip.jsonc+++ b/knip.jsonc@@ -39,13 +39,15 @@],},"web": {+ // Components imported by MDX documentation, which Knip does not trace.+ "entry": [".storybook/docs/**/*.tsx"],"ignoreFiles": [// Standalone benchmark invoked directly with Node rather than imported by the application."src/features/traces/components/AdvancedJsonViewer/lazy/benchByteJsonIndex.ts","src/__tests__/mocks/**",],// Include runtime JavaScript modules such as src/env.mjs in dependency analysis.- "project": ["src/**/*.{ts,tsx,mjs}"],+ "project": ["src/**/*.{ts,tsx,mjs}", ".storybook/docs/*.{ts,tsx}"],"ignoreDependencies": [// Tailwind loads this plugin from an @plugin directive in globals.css."@tailwindcss/forms",diff --git a/web/.storybook/docs.css b/web/.storybook/docs.cssindex 3d5ec9caa6..ba62f921f0 100644--- a/web/.storybook/docs.css+++ b/web/.storybook/docs.css@@ -36,6 +36,45 @@overflow-wrap: break-word;}+.sbdocs.sbdocs-content:has(.component-relationship-graph) {+ display: flex;+ height: 100vh;+ max-width: none;+ flex-direction: column;+ overflow: hidden;+ padding: var(--docs-space-6);+}++.component-relationship-node--component {+ fill: hsl(var(--chart-1) / 0.16);+ stroke: hsl(var(--chart-1));+}++.component-relationship-node--function {+ fill: hsl(var(--chart-2) / 0.16);+ stroke: hsl(var(--chart-2));+}++.component-relationship-node--internal {+ fill: hsl(var(--chart-4) / 0.16);+ stroke: hsl(var(--chart-4));+}++.component-relationship-key--component {+ background: hsl(var(--chart-1) / 0.16);+ border-color: hsl(var(--chart-1));+}++.component-relationship-key--function {+ background: hsl(var(--chart-2) / 0.16);+ border-color: hsl(var(--chart-2));+}++.component-relationship-key--internal {+ background: hsl(var(--chart-4) / 0.16);+ border-color: hsl(var(--chart-4));+}+.sbdocs.sbdocs-content .docblock-source {max-width: 52rem;margin-top: 0;diff --git a/web/.storybook/docs/ComponentRelationshipGraph.tsx b/web/.storybook/docs/ComponentRelationshipGraph.tsxnew file mode 100644index 0000000000..39ec4b9fcd--- /dev/null+++ b/web/.storybook/docs/ComponentRelationshipGraph.tsx@@ -0,0 +1,329 @@+import { select } from "d3-selection";+import { zoom, zoomIdentity } from "d3-zoom";+import type { ElkNode } from "elkjs";+import ELK from "elkjs/lib/elk.bundled.js";+import { useEffect, useMemo, useRef, useState } from "react";++import { Button } from "@/src/components/design-system/Button/Button";++import { buildComponentRelationshipGraph } from "./componentRelationshipData";++const sourceModules = import.meta.glob(+ "../../src/components/design-system/**/*.{ts,tsx}",+ {+ query: "?raw",+ import: "default",+ eager: true,+ },+) as Record<string, string>;++const NODE_WIDTH = 190;+const NODE_HEIGHT = 42;+const PADDING = 40;++type Layout = {+ width: number;+ height: number;+ nodes: {+ id: string;+ label: string;+ kind: "component" | "function" | "internal";+ group: string | null;+ x: number;+ y: number;+ }[];+ edges: { id: string; path: string }[];+ groupAreas: {+ label: string;+ x: number;+ y: number;+ width: number;+ height: number;+ }[];+};++const NODE_CLASSES = {+ component: "component-relationship-node--component",+ function: "component-relationship-node--function",+ internal: "component-relationship-node--internal",+} as const;++const graph = buildComponentRelationshipGraph(sourceModules);++async function layoutGraph() {+ const elk = new ELK();+ const groupedNodes = new Map<string, typeof graph.nodes>();+ for (const node of graph.nodes) {+ if (node.group === null) continue;+ groupedNodes.set(node.group, [+ ...(groupedNodes.get(node.group) ?? []),+ node,+ ]);+ }+ const groupedNodeIds = new Set(+ [...groupedNodes.values()].flat().map((node) => node.id),+ );+ const rootNodes = graph.nodes.filter((node) => !groupedNodeIds.has(node.id));+ const leafNode = (id: string): ElkNode => ({+ id,+ width: NODE_WIDTH,+ height: NODE_HEIGHT,+ });+ const elkGraph: ElkNode = {+ id: "root",+ layoutOptions: {+ "elk.algorithm": "layered",+ "elk.aspectRatio": "0.35",+ "elk.direction": "RIGHT",+ "elk.edgeRouting": "ORTHOGONAL",+ "elk.hierarchyHandling": "INCLUDE_CHILDREN",+ "elk.layered.spacing.nodeNodeBetweenLayers": "120",+ "elk.spacing.nodeNode": "32",+ "elk.spacing.componentComponent": "64",+ "elk.layered.crossingMinimization.strategy": "LAYER_SWEEP",+ "elk.layered.nodePlacement.strategy": "BRANDES_KOEPF",+ "elk.padding": `[top=${PADDING},left=${PADDING},bottom=${PADDING},right=${PADDING}]`,+ },+ children: [+ ...rootNodes.map((node) => leafNode(node.id)),+ ...[...groupedNodes.entries()].map(([group, nodes]) => ({+ id: `group:${group}`,+ layoutOptions: {+ "elk.algorithm": "layered",+ "elk.aspectRatio": "0.35",+ "elk.direction": "RIGHT",+ "elk.edgeRouting": "ORTHOGONAL",+ "elk.spacing.nodeNode": "24",+ "elk.padding": "[top=40,left=24,bottom=24,right=24]",+ },+ children: nodes.map((node) => leafNode(node.id)),+ })),+ ],+ edges: graph.edges.map((edge) => ({+ id: edge.id,+ sources: [edge.source],+ targets: [edge.target],+ })),+ };+ const result = await elk.layout(elkGraph);+ const graphNodes = new Map(graph.nodes.map((node) => [node.id, node]));+ const nodes: Layout["nodes"] = [];+ const groupAreas: Layout["groupAreas"] = [];++ for (const node of result.children ?? []) {+ if (!node.id.startsWith("group:")) {+ const graphNode = graphNodes.get(node.id);+ if (!graphNode) continue;+ nodes.push({+ ...graphNode,+ x: node.x ?? 0,+ y: node.y ?? 0,+ });+ continue;+ }++ const x = node.x ?? 0;+ const y = node.y ?? 0;+ groupAreas.push({+ label: node.id.slice("group:".length),+ x,+ y,+ width: node.width ?? 0,+ height: node.height ?? 0,+ });+ for (const child of node.children ?? []) {+ const graphNode = graphNodes.get(child.id);+ if (!graphNode) continue;+ nodes.push({+ ...graphNode,+ x: x + (child.x ?? 0),+ y: y + (child.y ?? 0),+ });+ }+ }++ const groupOffsets = new Map(+ (result.children ?? [])+ .filter((node) => node.id.startsWith("group:"))+ .map((node) => [node.id, { x: node.x ?? 0, y: node.y ?? 0 }]),+ );+ const edges = (result.edges ?? []).flatMap((edge) => {+ const section = edge.sections?.[0];+ if (!section) return [];+ const offset = edge.container+ ? (groupOffsets.get(edge.container) ?? { x: 0, y: 0 })+ : { x: 0, y: 0 };+ const points = [+ section.startPoint,+ ...(section.bendPoints ?? []),+ section.endPoint,+ ];+ return [+ {+ id: edge.id,+ path: points+ .map(+ (point, index) =>+ `${index === 0 ? "M" : "L"}${point.x + offset.x},${point.y + offset.y}`,+ )+ .join(" "),+ },+ ];+ });++ return {+ width: result.width ?? 1,+ height: result.height ?? 1,+ nodes,+ edges,+ groupAreas,+ } satisfies Layout;+}++export function ComponentRelationshipGraph() {+ const [layout, setLayout] = useState<Layout>();+ const svgRef = useRef<SVGSVGElement>(null);+ const contentRef = useRef<SVGGElement>(null);+ const zoomBehavior = useMemo(+ () =>+ zoom<SVGSVGElement, unknown>()+ .scaleExtent([0.25, 8])+ .on("zoom", (event) => {+ contentRef.current?.setAttribute("transform", event.transform);+ }),+ [],+ );++ useEffect(() => {+ let active = true;+ layoutGraph().then((nextLayout) => {+ if (active) setLayout(nextLayout);+ });+ return () => {+ active = false;+ };+ }, []);++ useEffect(() => {+ const svg = svgRef.current;+ if (!svg) return;+ select(svg).call(zoomBehavior);+ return () => {+ select(svg).on(".zoom", null);+ };+ }, [layout, zoomBehavior]);++ const resetZoom = () => {+ if (!svgRef.current) return;+ select(svgRef.current).call(zoomBehavior.transform, zoomIdentity);+ };++ return (+ <div className="component-relationship-graph flex min-h-0 flex-1 flex-col gap-3">+ <div className="text-muted-foreground flex flex-wrap items-center justify-between gap-2 text-xs">+ <div className="flex flex-wrap items-center gap-3">+ <span>+ {graph.nodes.length} nodes · {graph.edges.length} imports · arrows+ point toward dependencies+ </span>+ <span className="flex items-center gap-1.5">+ <span className="component-relationship-key--component size-2.5 rounded-sm border" />+ Component+ </span>+ <span className="flex items-center gap-1.5">+ <span className="component-relationship-key--function size-2.5 rounded-sm border" />+ Function+ </span>+ <span className="flex items-center gap-1.5">+ <span className="component-relationship-key--internal size-2.5 rounded-sm border" />+ Internal component+ </span>+ </div>+ <Button text="Reset view" variant="secondary" onClick={resetZoom} />+ </div>+ <div className="bg-background min-h-0 flex-1 overflow-hidden rounded-md border">+ {layout ? (+ <svg+ ref={svgRef}+ className="size-full cursor-grab active:cursor-grabbing"+ viewBox={`0 0 ${layout.width} ${layout.height}`}+ aria-label="Design-system component import graph"+ >+ <defs>+ <marker+ id="dependency-arrow"+ viewBox="0 0 10 10"+ refX="9"+ refY="5"+ markerWidth="6"+ markerHeight="6"+ orient="auto-start-reverse"+ >+ <path+ d="M 0 0 L 10 5 L 0 10 z"+ className="fill-muted-foreground"+ />+ </marker>+ </defs>+ <g ref={contentRef}>+ {layout.groupAreas.map((area) => (+ <g key={area.label}>+ <rect+ x={area.x}+ y={area.y}+ width={area.width}+ height={area.height}+ rx="8"+ className="fill-muted/30 stroke-border stroke-dashed"+ />+ <text+ x={area.x + 12}+ y={area.y + 20}+ className="fill-muted-foreground text-[10px] font-medium tracking-wide uppercase"+ >+ {area.label}+ </text>+ </g>+ ))}+ {layout.edges.map((edge) => (+ <path+ key={edge.id}+ d={edge.path}+ fill="none"+ markerEnd="url(#dependency-arrow)"+ className="stroke-muted-foreground/50"+ />+ ))}+ {layout.nodes.map((node) => (+ <g key={node.id} transform={`translate(${node.x} ${node.y})`}>+ <rect+ width={NODE_WIDTH}+ height={NODE_HEIGHT}+ rx="6"+ className={NODE_CLASSES[node.kind]}+ />+ <text+ x={NODE_WIDTH / 2}+ y={NODE_HEIGHT / 2}+ dominantBaseline="middle"+ textAnchor="middle"+ className="fill-foreground text-[11px] font-medium"+ >+ {node.label}+ </text>+ </g>+ ))}+ </g>+ </svg>+ ) : (+ <div className="text-muted-foreground flex size-full items-center justify-center text-sm">+ Laying out component graph…+ </div>+ )}+ </div>+ <p className="text-muted-foreground text-xs">+ Drag to pan and scroll to zoom.+ </p>+ </div>+ );+}diff --git a/web/.storybook/docs/ComponentRelationships.mdx b/web/.storybook/docs/ComponentRelationships.mdxnew file mode 100644index 0000000000..7c15093be8--- /dev/null+++ b/web/.storybook/docs/ComponentRelationships.mdx@@ -0,0 +1,10 @@+import { Meta } from "@storybook/addon-docs/blocks";+import { ComponentRelationshipGraph } from "./ComponentRelationshipGraph";++<Meta title="Component Relationships" />++# Component Relationships++This graph shows imports between components in the design system.++<ComponentRelationshipGraph />diff --git a/web/.storybook/docs/componentRelationshipData.test.ts b/web/.storybook/docs/componentRelationshipData.test.tsnew file mode 100644index 0000000000..c171c962c9--- /dev/null+++ b/web/.storybook/docs/componentRelationshipData.test.ts@@ -0,0 +1,90 @@+import { describe, expect, it } from "vitest";++import { buildComponentRelationshipGraph } from "./componentRelationshipData";++describe("buildComponentRelationshipGraph", () => {+ it("builds component-level edges from alias and relative imports", () => {+ const graph = buildComponentRelationshipGraph({+ "../../src/components/design-system/Button/Button.tsx": "export {}",+ "../../src/components/design-system/Dialog/Dialog.tsx":+ 'import { Button } from "@/src/components/design-system/Button/Button";',+ "../../src/components/design-system/Form/Form.tsx":+ 'export { Dialog } from "../Dialog/Dialog";',+ "../../src/components/design-system/Form/Form.stories.tsx":+ 'import { Checkbox } from "../Checkbox/Checkbox";',+ });++ expect(graph).toEqual({+ nodes: [+ {+ id: "Button",+ label: "Button",+ kind: "component",+ group: null,+ },+ {+ id: "Dialog",+ label: "Dialog",+ kind: "component",+ group: null,+ },+ { id: "Form", label: "Form", kind: "component", group: null },+ ],+ edges: [+ { id: "Dialog->Button", source: "Dialog", target: "Button" },+ { id: "Form->Dialog", source: "Form", target: "Dialog" },+ ],+ });+ });++ it("keeps nested design-system areas readable", () => {+ const graph = buildComponentRelationshipGraph({+ "../../src/components/design-system/table/columns/createTextTableColumn.tsx":+ 'import { EmptyValue } from "../components/EmptyValue/EmptyValue";',+ "../../src/components/design-system/table/components/EmptyValue/EmptyValue.tsx":+ "export {};",+ "../../src/components/design-system/internal/InputControl/InputControl.tsx":+ "export {};",+ });++ expect(graph.nodes.map(({ id }) => id)).toEqual([+ "Internal / InputControl",+ "Table / createTextTableColumn",+ "Table / EmptyValue",+ ]);+ expect(graph.nodes.map(({ kind }) => kind)).toEqual([+ "internal",+ "function",+ "component",+ ]);+ expect(graph.edges).toEqual([+ {+ id: "Table / createTextTableColumn->Table / EmptyValue",+ source: "Table / createTextTableColumn",+ target: "Table / EmptyValue",+ },+ ]);+ });++ it("excludes imports that leave the design-system directory", () => {+ const graph = buildComponentRelationshipGraph({+ "../../src/components/design-system/Button/Button.tsx":+ 'import { Dialog } from "../../Dialog/Dialog";',+ "../../src/components/design-system/Dialog/Dialog.tsx": "export {};",+ });++ expect(graph.edges).toEqual([]);+ });++ it("groups new lowercase top-level directories automatically", () => {+ const graph = buildComponentRelationshipGraph({+ "../../src/components/design-system/utilities/formatLabel.ts":+ "export {};",+ });++ expect(graph.nodes[0]).toMatchObject({+ id: "Utilities / formatLabel",+ group: "Utilities",+ });+ });+});diff --git a/web/.storybook/docs/componentRelationshipData.ts b/web/.storybook/docs/componentRelationshipData.tsnew file mode 100644index 0000000000..a9b5f3bad3--- /dev/null+++ b/web/.storybook/docs/componentRelationshipData.ts@@ -0,0 +1,147 @@+export type ComponentRelationshipGraph = {+ nodes: {+ id: string;+ label: string;+ kind: "component" | "function" | "internal";+ group: string | null;+ }[];+ edges: { id: string; source: string; target: string }[];+};++const DESIGN_SYSTEM_PATH = "/src/components/design-system/";+const DESIGN_SYSTEM_ALIAS = "@/src/components/design-system/";+const SOURCE_FILE_PATTERN = /\.(?:ts|tsx)$/;+const NON_COMPONENT_FILE_PATTERN =+ /\.(?:stories|clienttest|servertest|test|spec)\.(?:ts|tsx)$/;+const STATIC_IMPORT_PATTERN =+ /(?:import|export)\s+(?:type\s+)?(?:[^;"']*?\s+from\s+)?["']([^"']+)["']/g;++function normalizePath(path: string) {+ const segments: string[] = [];+ for (const segment of path.split("/")) {+ if (segment === "" || segment === ".") continue;+ if (segment === "..") {+ segments.pop();+ continue;+ }+ segments.push(segment);+ }+ return segments.join("/");+}++function relativeDesignSystemPath(path: string) {+ const normalized = `/${normalizePath(path)}`;+ const markerIndex = normalized.indexOf(DESIGN_SYSTEM_PATH);+ if (markerIndex === -1) return null;+ return normalized.slice(markerIndex + DESIGN_SYSTEM_PATH.length);+}++function componentId(path: string) {+ const [area, ...segments] = path.split("/");+ if (!area) return null;+ if (/^[A-Z]/.test(area)) return area;+ const group = `${area.charAt(0).toUpperCase()}${area.slice(1)}`;+ const subject =+ segments.find((segment) => /^[A-Z]/.test(segment)) ?? segments.at(-1);+ if (!subject) return group;+ return `${group} / ${subject.replace(SOURCE_FILE_PATTERN, "")}`;+}++function nodeGroup(path: string) {+ const area = path.split("/")[0];+ if (!area || /^[A-Z]/.test(area)) return null;+ return `${area.charAt(0).toUpperCase()}${area.slice(1)}`;+}++function nodeKind(path: string) {+ if (path.startsWith("internal/")) return "internal" as const;+ if (path.startsWith("factories/") || path.startsWith("table/columns/")) {+ return "function" as const;+ }+ return "component" as const;+}++function resolveImport(importer: string, specifier: string) {+ if (specifier.startsWith(DESIGN_SYSTEM_ALIAS)) {+ return specifier.slice(DESIGN_SYSTEM_ALIAS.length);+ }+ if (!specifier.startsWith(".")) return null;+ const segments = importer.split("/").slice(0, -1);+ for (const segment of specifier.split("/")) {+ if (segment === "" || segment === ".") continue;+ if (segment === "..") {+ if (segments.length === 0) return null;+ segments.pop();+ continue;+ }+ segments.push(segment);+ }+ return segments.join("/");+}++export function buildComponentRelationshipGraph(+ sourceModules: Record<string, string>,+): ComponentRelationshipGraph {+ const modules = Object.entries(sourceModules).flatMap(([path, source]) => {+ const relativePath = relativeDesignSystemPath(path);+ if (+ relativePath === null ||+ !SOURCE_FILE_PATTERN.test(relativePath) ||+ NON_COMPONENT_FILE_PATTERN.test(relativePath)+ ) {+ return [];+ }+ const id = componentId(relativePath);+ return id === null+ ? []+ : [+ {+ id,+ group: nodeGroup(relativePath),+ kind: nodeKind(relativePath),+ path: relativePath,+ source,+ },+ ];+ });++ const nodeDetails = new Map(+ modules.map(({ id, kind, group }) => [id, { kind, group }]),+ );+ const nodeIds = new Set(nodeDetails.keys());+ const edgePairs = new Set<string>();++ for (const sourceModule of modules) {+ for (const match of sourceModule.source.matchAll(STATIC_IMPORT_PATTERN)) {+ const importedPath = resolveImport(sourceModule.path, match[1]);+ if (importedPath === null) continue;+ const target = componentId(importedPath);+ if (target === null || target === sourceModule.id || !nodeIds.has(target))+ continue;+ edgePairs.add(JSON.stringify([sourceModule.id, target]));+ }+ }++ const nodes = [...nodeIds]+ .sort((left, right) => left.localeCompare(right))+ .map((id) => ({+ id,+ label: id,+ kind: nodeDetails.get(id)?.kind ?? "component",+ group: nodeDetails.get(id)?.group ?? null,+ }));+ const edges = [...edgePairs]+ .map((pair) => JSON.parse(pair) as [string, string])+ .sort(([leftSource, leftTarget], [rightSource, rightTarget]) =>+ `${leftSource}\0${leftTarget}`.localeCompare(+ `${rightSource}\0${rightTarget}`,+ ),+ )+ .map(([source, target]) => ({+ id: `${source}->${target}`,+ source,+ target,+ }));++ return { nodes, edges };+}diff --git a/web/playwright.config.ts b/web/playwright.config.tsindex dc4d044419..3bda799baa 100644--- a/web/playwright.config.ts+++ b/web/playwright.config.ts@@ -1,6 +1,7 @@import { defineConfig } from "@playwright/test";export default defineConfig({+ testDir: "./src/__e2e__",timeout: 180000, // test timeout 180s (3 minutes)expect: {timeout: 60000, // assertion timeout 60s (increased for CI)