From 585a694334c4db504c72c0ddae13a146710b5f18 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:29:19 +0200
Subject: [PATCH 01/36] feat: clicking user icon in sidebar opens profile
 settings (#351)

Convert the user footer section from a static div to a clickable
button that navigates to /settings/profile. Adds cursor-pointer,
hover styling, and aria-label for keyboard accessibility.

Closes #351

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/src/app/(dashboard)/layout.tsx | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/app/src/app/(dashboard)/layout.tsx b/app/src/app/(dashboard)/layout.tsx
index 063bb2ed..a314db4a 100644
--- a/app/src/app/(dashboard)/layout.tsx
+++ b/app/src/app/(dashboard)/layout.tsx
@@ -86,8 +86,11 @@ export default function DashboardLayout({
           footer={
             <>
               {userName && (
-                <div
-                  className={`flex items-center gap-2 px-3 py-2 text-sm ${collapsed ? "justify-center" : ""}`}
+                <button
+                  type="button"
+                  onClick={() => router.push("/settings/profile")}
+                  aria-label="Open profile settings"
+                  className={`flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm cursor-pointer hover:bg-accent hover:text-accent-foreground transition-colors ${collapsed ? "justify-center" : ""}`}
                 >
                   <User className="h-4 w-4 shrink-0 text-muted-foreground" />
                   {!collapsed && (
@@ -103,7 +106,7 @@ export default function DashboardLayout({
                       )}
                     </span>
                   )}
-                </div>
+                </button>
               )}
               <DropdownMenu>
                 <DropdownMenuTrigger asChild>

From f1fcf071b9a03498f9fa58a46460ec1234ca57bd Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:32:03 +0200
Subject: [PATCH 02/36] fix: bar chart blank render on initial widget placement
 (#332)

When a widget is first placed on a dashboard grid, the container
often starts with 0 dimensions during ECharts init. The first
setOption() draws to a 0x0 canvas, leaving the chart blank until
the user resizes or reloads.

Force instance.resize() after setOption so the chart picks up the
real container size on first render.

Closes #332

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 component/src/charts/base-chart.tsx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/component/src/charts/base-chart.tsx b/component/src/charts/base-chart.tsx
index caf64ed9..316b72fd 100644
--- a/component/src/charts/base-chart.tsx
+++ b/component/src/charts/base-chart.tsx
@@ -205,6 +205,10 @@ function BaseChart({
       },
     };
     instance.setOption(merged, { notMerge: true });
+    // Fix blank render on initial widget placement: if the container was
+    // 0x0 when ECharts initialized, the first setOption draws to a 0x0
+    // canvas. Force a resize after setOption so it picks up the real size.
+    instance.resize();
   }, [
     options,
     enableDataZoom,

From 2e47ff7134866e1356ccccda2822062f8f90ef9d Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:34:17 +0200
Subject: [PATCH 03/36] feat: responsive bar chart label rotation based on
 widget width (#337)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

buildCategoryAxisLabel now considers container width when computing
rotation — narrower containers rotate more aggressively so labels
don't overlap.

Thresholds (pixels per label):
- < 40px: 60°
- < 70px: 45°
- < 100px: 30°
- >= 100px: 0°

Also tightens label truncation to 10 chars when container is < 400px.

Closes #337

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 component/src/charts/bar-chart.tsx  | 56 ++++++++++++++++++++++++-----
 component/src/charts/chart-utils.ts | 30 +++++++++++++---
 2 files changed, 73 insertions(+), 13 deletions(-)

diff --git a/component/src/charts/bar-chart.tsx b/component/src/charts/bar-chart.tsx
index 0e741dca..f92e3d97 100644
--- a/component/src/charts/bar-chart.tsx
+++ b/component/src/charts/bar-chart.tsx
@@ -84,11 +84,17 @@ function BarChart({
     if (!data.length) return buildEmptyDataOption();
 
     const seriesKeys = Object.keys(data[0]).filter((k) => k !== "label");
-    const effectiveShowLegend = resolveShowLegend(showLegend, seriesKeys.length, hideLegend);
+    const effectiveShowLegend = resolveShowLegend(
+      showLegend,
+      seriesKeys.length,
+      hideLegend,
+    );
     const isHorizontal = orientation === "horizontal";
     const effectiveShowValues = compact ? false : showValues;
     const effectiveBarWidth = barWidth > 0 ? barWidth : undefined;
-    const thresholds = stylingRules ? [] : parseColorThresholds(colorThresholds ?? "");
+    const thresholds = stylingRules
+      ? []
+      : parseColorThresholds(colorThresholds ?? "");
     const refLines = parseReferenceLines(referenceLinesJson);
     const markLine = buildMarkLineFromRefs(refLines);
 
@@ -96,6 +102,7 @@ function BarChart({
     const axisLabelConfig = buildCategoryAxisLabel(categoryLabels.length, {
       compact,
       rotateOverride: axisLabelRotation,
+      containerWidth: width,
     });
 
     const categoryAxis = {
@@ -103,7 +110,7 @@ function BarChart({
       data: categoryLabels,
       axisLabel: axisLabelConfig,
       axisPointer: { type: "shadow" as const },
-      name: compact ? undefined : (isHorizontal ? yAxisLabel : xAxisLabel),
+      name: compact ? undefined : isHorizontal ? yAxisLabel : xAxisLabel,
       nameLocation: "middle" as const,
       nameGap: axisLabelConfig.rotate > 0 ? 50 : 30,
     };
@@ -111,13 +118,17 @@ function BarChart({
       type: "value" as const,
       axisLabel: { show: !compact },
       splitLine: { show: showGridLines },
-      name: compact ? undefined : (isHorizontal ? xAxisLabel : yAxisLabel),
+      name: compact ? undefined : isHorizontal ? xAxisLabel : yAxisLabel,
       nameLocation: "middle" as const,
       nameGap: 50,
     };
 
     return {
-      tooltip: { trigger: "axis" as const, axisPointer: { type: "shadow" as const }, formatter: buildTooltipFormatter() },
+      tooltip: {
+        trigger: "axis" as const,
+        axisPointer: { type: "shadow" as const },
+        formatter: buildTooltipFormatter(),
+      },
       legend: effectiveShowLegend ? { bottom: 0 } : undefined,
       grid: buildCompactGrid(compact, effectiveShowLegend),
       xAxis: isHorizontal ? valueAxis : categoryAxis,
@@ -127,9 +138,15 @@ function BarChart({
         type: "bar" as const,
         data: data.map((d) => {
           const rawValue = d[key];
-          const numericValue = typeof rawValue === "number" ? rawValue : Number(rawValue);
+          const numericValue =
+            typeof rawValue === "number" ? rawValue : Number(rawValue);
           const color = Number.isFinite(numericValue)
-            ? resolveItemColor(numericValue, stylingRules, paramValues, thresholds)
+            ? resolveItemColor(
+                numericValue,
+                stylingRules,
+                paramValues,
+                thresholds,
+              )
             : undefined;
           return color ? { value: rawValue, itemStyle: { color } } : rawValue;
         }),
@@ -137,14 +154,35 @@ function BarChart({
         barWidth: effectiveBarWidth,
         barGap,
         label: effectiveShowValues
-          ? { show: true, position: isHorizontal ? ("right" as const) : ("top" as const) }
+          ? {
+              show: true,
+              position: isHorizontal ? ("right" as const) : ("top" as const),
+            }
           : undefined,
         emphasis: seriesKeys.length > 1 ? { focus: "series" as const } : {},
         // Attach reference lines to the first series only
         ...(idx === 0 && markLine ? { markLine } : {}),
       })),
     };
-  }, [data, orientation, stacked, showValues, showLegend, barWidth, barGap, showGridLines, xAxisLabel, yAxisLabel, axisLabelRotation, referenceLinesJson, colorThresholds, stylingRules, paramValues, compact, hideLegend]);
+  }, [
+    data,
+    orientation,
+    stacked,
+    showValues,
+    showLegend,
+    barWidth,
+    barGap,
+    showGridLines,
+    xAxisLabel,
+    yAxisLabel,
+    axisLabelRotation,
+    referenceLinesJson,
+    colorThresholds,
+    stylingRules,
+    paramValues,
+    compact,
+    hideLegend,
+  ]);
 
   return (
     <div ref={containerRef} className="h-full w-full">
diff --git a/component/src/charts/chart-utils.ts b/component/src/charts/chart-utils.ts
index dcabd632..11405588 100644
--- a/component/src/charts/chart-utils.ts
+++ b/component/src/charts/chart-utils.ts
@@ -133,6 +133,8 @@ export interface CategoryAxisLabelOptions {
   maxLabelLength?: number;
   /** Whether the chart is in compact mode (hides labels). */
   compact?: boolean;
+  /** Container width in pixels — used for width-based auto-rotation. */
+  containerWidth?: number;
 }
 
 export interface CategoryAxisLabelConfig {
@@ -156,7 +158,7 @@ export function buildCategoryAxisLabel(
   categoryCount: number,
   options: CategoryAxisLabelOptions = {},
 ): CategoryAxisLabelConfig {
-  const { maxLabelLength = 15, compact = false } = options;
+  const { maxLabelLength = 15, compact = false, containerWidth } = options;
   // Normalize -1 sentinel (automatic mode) to undefined so ECharts uses its
   // default auto-rotation instead of receiving an invalid rotate: -1.
   const rotateOverride =
@@ -165,6 +167,19 @@ export function buildCategoryAxisLabel(
   let rotate: number;
   if (rotateOverride !== undefined) {
     rotate = rotateOverride;
+  } else if (containerWidth && categoryCount > 0) {
+    // Width-aware rotation: compute available space per label.
+    // Rough budget: label width ≈ maxLabelLength * 7px at 12px font.
+    const pixelsPerLabel = containerWidth / categoryCount;
+    if (pixelsPerLabel < 40) {
+      rotate = 60;
+    } else if (pixelsPerLabel < 70) {
+      rotate = 45;
+    } else if (pixelsPerLabel < 100) {
+      rotate = 30;
+    } else {
+      rotate = 0;
+    }
   } else if (categoryCount >= 15) {
     rotate = 45;
   } else if (categoryCount >= 8) {
@@ -173,11 +188,18 @@ export function buildCategoryAxisLabel(
     rotate = 0;
   }
 
-  const needsTruncation = categoryCount >= 8;
+  // Width-aware truncation: tighter limit in narrow containers
+  const effectiveMaxLength =
+    containerWidth && containerWidth < 400
+      ? Math.min(maxLabelLength, 10)
+      : maxLabelLength;
+  const needsTruncation =
+    categoryCount >= 8 ||
+    (containerWidth !== undefined && containerWidth < 400);
   const formatter = needsTruncation
     ? (value: string) =>
-        value.length > maxLabelLength
-          ? value.slice(0, maxLabelLength - 1) + "\u2026"
+        value.length > effectiveMaxLength
+          ? value.slice(0, effectiveMaxLength - 1) + "\u2026"
           : value
     : undefined;
 

From 558f1dc7f6ae2918e0bce91856ddbc6f55fc3d9b Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:40:49 +0200
Subject: [PATCH 04/36] feat: scrollable pie chart legend with better controls
 (#338)

---
 .../src/charts/__tests__/pie-chart.test.tsx   | 25 +++++-
 component/src/charts/pie-chart.tsx            | 85 ++++++++++++++-----
 2 files changed, 88 insertions(+), 22 deletions(-)

diff --git a/component/src/charts/__tests__/pie-chart.test.tsx b/component/src/charts/__tests__/pie-chart.test.tsx
index 3e4e37e7..326eb64a 100644
--- a/component/src/charts/__tests__/pie-chart.test.tsx
+++ b/component/src/charts/__tests__/pie-chart.test.tsx
@@ -68,6 +68,18 @@ describe("PieChart", () => {
     expect(optionsCall.legend).toBeUndefined();
   });
 
+  it("configures legend with scrollable type and enlarged pagination controls", () => {
+    render(<PieChart data={sampleData} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.legend).toMatchObject({
+      type: "scroll",
+      bottom: 0,
+      orient: "horizontal",
+      pageIconSize: 12,
+    });
+    expect(optionsCall.legend.pageTextStyle.fontSize).toBe(11);
+  });
+
   it("handles empty data", () => {
     render(<PieChart data={[]} />);
     const optionsCall = mockSetOption.mock.calls[0][0];
@@ -121,14 +133,18 @@ describe("PieChart", () => {
   it("sorts slices by value descending when sortSlices is true", () => {
     render(<PieChart data={sampleData} sortSlices />);
     const optionsCall = mockSetOption.mock.calls[0][0];
-    const values = (optionsCall.series[0].data as Array<{ value: number }>).map((d) => d.value);
+    const values = (optionsCall.series[0].data as Array<{ value: number }>).map(
+      (d) => d.value,
+    );
     expect(values).toEqual([60, 30, 10]);
   });
 
   it("preserves original order when sortSlices is false (default)", () => {
     render(<PieChart data={sampleData} />);
     const optionsCall = mockSetOption.mock.calls[0][0];
-    const names = (optionsCall.series[0].data as Array<{ name: string }>).map((d) => d.name);
+    const names = (optionsCall.series[0].data as Array<{ name: string }>).map(
+      (d) => d.name,
+    );
     expect(names).toEqual(["Desktop", "Mobile", "Tablet"]);
   });
 
@@ -160,7 +176,10 @@ describe("PieChart", () => {
   it("groups slices beyond topN into Other", () => {
     render(<PieChart data={sampleData} topN={2} />);
     const optionsCall = mockSetOption.mock.calls[0][0];
-    const seriesData = optionsCall.series[0].data as Array<{ name: string; value: number }>;
+    const seriesData = optionsCall.series[0].data as Array<{
+      name: string;
+      value: number;
+    }>;
     expect(seriesData).toHaveLength(3); // 2 top + "Other"
     expect(seriesData[2].name).toBe("Other");
     expect(seriesData[2].value).toBe(10);
diff --git a/component/src/charts/pie-chart.tsx b/component/src/charts/pie-chart.tsx
index ff6549f6..fd1326df 100644
--- a/component/src/charts/pie-chart.tsx
+++ b/component/src/charts/pie-chart.tsx
@@ -3,7 +3,13 @@ import type { EChartsOption } from "echarts";
 import { BaseChart } from "./base-chart";
 import type { BaseChartProps, PieChartDataPoint } from "./types";
 import { useContainerSize } from "@/hooks/useContainerSize";
-import { buildEmptyDataOption, getCompactState, isDark, resolveItemColor, groupTopN } from "./chart-utils";
+import {
+  buildEmptyDataOption,
+  getCompactState,
+  isDark,
+  resolveItemColor,
+  groupTopN,
+} from "./chart-utils";
 import { parseColorThresholds } from "./color-threshold";
 import type { StylingRule } from "./styling-rule";
 
@@ -77,9 +83,16 @@ function PieChart({
       : data;
     const sortedData = groupTopN(sorted, topN);
 
-    const thresholds = stylingRules ? [] : parseColorThresholds(colorThresholds ?? "");
+    const thresholds = stylingRules
+      ? []
+      : parseColorThresholds(colorThresholds ?? "");
     const coloredData = sortedData.map((d) => {
-      const color = resolveItemColor(d.value, stylingRules, paramValues, thresholds);
+      const color = resolveItemColor(
+        d.value,
+        stylingRules,
+        paramValues,
+        thresholds,
+      );
       return color ? { ...d, itemStyle: { color } } : d;
     });
 
@@ -91,7 +104,19 @@ function PieChart({
         trigger: "item",
         formatter: "{b}: {c} ({d}%)",
       },
-      legend: effectiveShowLegend ? { bottom: 0, type: "scroll" } : undefined,
+      legend: effectiveShowLegend
+        ? {
+            bottom: 0,
+            type: "scroll",
+            orient: "horizontal",
+            width: "90%",
+            pageIconSize: 12,
+            pageTextStyle: { fontSize: 11 },
+            pageButtonItemGap: 6,
+            itemGap: 12,
+            textStyle: { fontSize: 12 },
+          }
+        : undefined,
       series: [
         {
           type: "pie",
@@ -121,22 +146,44 @@ function PieChart({
         },
       ],
       // Donut center text: show total or custom text in the center hole
-      ...(donut && !compact ? {
-        graphic: [{
-          type: "text",
-          left: "center",
-          top: effectiveShowLegend ? "42%" : "47%",
-          style: {
-            text: donutCenterText ?? String(sortedData.reduce((s, d) => s + d.value, 0)),
-            align: "center",
-            fontSize: 20,
-            fontWeight: "bold",
-            fill: isDark() ? "#e5e5e5" : "#262626",
-          },
-        }],
-      } : {}),
+      ...(donut && !compact
+        ? {
+            graphic: [
+              {
+                type: "text",
+                left: "center",
+                top: effectiveShowLegend ? "42%" : "47%",
+                style: {
+                  text:
+                    donutCenterText ??
+                    String(sortedData.reduce((s, d) => s + d.value, 0)),
+                  align: "center",
+                  fontSize: 20,
+                  fontWeight: "bold",
+                  fill: isDark() ? "#e5e5e5" : "#262626",
+                },
+              },
+            ],
+          }
+        : {}),
     };
-  }, [data, donut, showLabel, showLegend, roseMode, labelPosition, showPercentage, sortSlices, topN, donutCenterText, colorThresholds, stylingRules, paramValues, compact, hideLegend]);
+  }, [
+    data,
+    donut,
+    showLabel,
+    showLegend,
+    roseMode,
+    labelPosition,
+    showPercentage,
+    sortSlices,
+    topN,
+    donutCenterText,
+    colorThresholds,
+    stylingRules,
+    paramValues,
+    compact,
+    hideLegend,
+  ]);
 
   return (
     <div ref={containerRef} className="h-full w-full">

From 4704a426ee7562940e698abbfa44e60b12505ef8 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:42:52 +0200
Subject: [PATCH 05/36] feat: connect nulls and end labels for line chart
 (#146)

Add two new boolean options to LineChart:
- connectNulls: draw lines through missing (null) data points
- endLabel: show series name label at the end of each line

Exposed via the chart options schema so users can toggle in the UI.

Closes #146

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../src/charts/__tests__/line-chart.test.tsx  | 51 +++++++++++++++++++
 component/src/charts/line-chart.tsx           | 10 ++++
 .../components/composed/chart-options/line.ts | 17 +++++++
 3 files changed, 78 insertions(+)

diff --git a/component/src/charts/__tests__/line-chart.test.tsx b/component/src/charts/__tests__/line-chart.test.tsx
index c33c2962..fc8676d9 100644
--- a/component/src/charts/__tests__/line-chart.test.tsx
+++ b/component/src/charts/__tests__/line-chart.test.tsx
@@ -160,6 +160,57 @@ describe("LineChart", () => {
     expect(optionsCall.series[0].step).toBeUndefined();
   });
 
+  // --- Connect nulls ---
+
+  it("defaults connectNulls to false", () => {
+    render(<LineChart data={sampleData} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].connectNulls).toBe(false);
+  });
+
+  it("enables connectNulls when true", () => {
+    render(<LineChart data={sampleData} connectNulls />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].connectNulls).toBe(true);
+  });
+
+  it("applies connectNulls to every series in multi-series", () => {
+    render(<LineChart data={multiSeriesData} connectNulls />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].connectNulls).toBe(true);
+    expect(optionsCall.series[1].connectNulls).toBe(true);
+  });
+
+  // --- End label ---
+
+  it("does not set endLabel by default", () => {
+    render(<LineChart data={sampleData} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].endLabel).toBeUndefined();
+  });
+
+  it("enables endLabel when true", () => {
+    render(<LineChart data={sampleData} endLabel />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].endLabel).toEqual({
+      show: true,
+      formatter: "{a}",
+    });
+  });
+
+  it("applies endLabel to every series in multi-series", () => {
+    render(<LineChart data={multiSeriesData} endLabel />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].endLabel).toEqual({
+      show: true,
+      formatter: "{a}",
+    });
+    expect(optionsCall.series[1].endLabel).toEqual({
+      show: true,
+      formatter: "{a}",
+    });
+  });
+
   // --- Reference lines ---
 
   it("attaches markLine to the first series when referenceLines is provided", () => {
diff --git a/component/src/charts/line-chart.tsx b/component/src/charts/line-chart.tsx
index c2b5136e..6469e53a 100644
--- a/component/src/charts/line-chart.tsx
+++ b/component/src/charts/line-chart.tsx
@@ -38,6 +38,10 @@ export interface LineChartProps extends Omit<BaseChartProps, "options"> {
   showGridLines?: boolean;
   /** Use stepped line style */
   stepped?: boolean;
+  /** Draw lines through missing (null) data points */
+  connectNulls?: boolean;
+  /** Show series name label at the end of each line */
+  endLabel?: boolean;
   /** JSON string of reference lines: [{ value, label?, color? }] */
   referenceLines?: string;
   /** @deprecated Use stylingRules instead. JSON string of thresholds */
@@ -68,6 +72,8 @@ function LineChart({
   lineWidth = 2,
   showGridLines = true,
   stepped = false,
+  connectNulls = false,
+  endLabel = false,
   referenceLines: referenceLinesJson,
   colorThresholds,
   stylingRules,
@@ -140,6 +146,8 @@ function LineChart({
             : data.map((d) => d[key] as number),
           smooth,
           step: stepped ? ("start" as const) : undefined,
+          connectNulls,
+          endLabel: endLabel ? { show: true, formatter: "{a}" } : undefined,
           lineStyle: { width: lineWidth, color: seriesColor },
           itemStyle: seriesColor ? { color: seriesColor } : undefined,
           showSymbol: showPoints,
@@ -165,6 +173,8 @@ function LineChart({
     lineWidth,
     showGridLines,
     stepped,
+    connectNulls,
+    endLabel,
     referenceLinesJson,
     colorThresholds,
     stylingRules,
diff --git a/component/src/components/composed/chart-options/line.ts b/component/src/components/composed/chart-options/line.ts
index b4046183..a2a8c8ae 100644
--- a/component/src/components/composed/chart-options/line.ts
+++ b/component/src/components/composed/chart-options/line.ts
@@ -51,6 +51,23 @@ export const lineOptions: ChartOptionDef[] = [
     category: "Style",
     description: "Draw a dot at each data point along the line.",
   },
+  {
+    key: "connectNulls",
+    label: "Connect Nulls",
+    type: "boolean",
+    default: false,
+    category: "Style",
+    description:
+      "Draw a continuous line through missing (null) data points instead of breaking the line.",
+  },
+  {
+    key: "endLabel",
+    label: "Show End Labels",
+    type: "boolean",
+    default: false,
+    category: "Style",
+    description: "Show the series name as a label at the end of each line.",
+  },
   SHARED_SHOW_GRID_LINES,
   SHARED_X_AXIS_LABEL,
   SHARED_Y_AXIS_LABEL,

From 8ee84044f740a9ccff096b11b354fe0af3bd4925 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:43:59 +0200
Subject: [PATCH 06/36] fix: show ID and entity type in graph inspection panel
 (#352)

- Add edge ID to metadata items in relationship inspection panel
- Add Badge indicator showing 'Node' or 'Relationship' in panel header
- Thread optional id through GraphEdge type and transform pipeline so
  the inspection panel can surface the internal element id for edges

Closes #352

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../components/graph-exploration-wrapper.tsx  | 21 ++++++++++++-------
 app/src/lib/chart-registry.ts                 |  1 +
 component/src/charts/types.ts                 |  1 +
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/app/src/components/graph-exploration-wrapper.tsx b/app/src/components/graph-exploration-wrapper.tsx
index 91c5cde3..efb2d352 100644
--- a/app/src/components/graph-exploration-wrapper.tsx
+++ b/app/src/components/graph-exploration-wrapper.tsx
@@ -6,6 +6,7 @@ import {
   GraphChart,
   useGraphExploration,
   PropertyPanel,
+  Badge,
 } from "@neoboard/components";
 import type {
   GraphNode,
@@ -119,6 +120,7 @@ function edgeToSections(edge: GraphEdge): PropertySection[] {
     };
   });
   const metaItems = [
+    ...(edge.id ? [{ key: "id", value: edge.id }] : []),
     { key: "type", value: edge.label ?? "UNKNOWN" },
     { key: "source", value: edge.source },
     { key: "target", value: edge.target },
@@ -332,13 +334,18 @@ export function GraphExplorationWrapper({
       {inspectedElement && (
         <div className="absolute top-0 right-0 bottom-0 w-80 border-l bg-background/95 backdrop-blur-sm overflow-y-auto z-20 shadow-lg">
           <div className="flex items-center justify-between p-3 border-b">
-            <h3 className="text-sm font-semibold">
-              {inspectedElement.type === "node"
-                ? (inspectedElement.node.label ??
-                  inspectedElement.node.id ??
-                  "Node")
-                : (inspectedElement.edge.label ?? "Relationship")}
-            </h3>
+            <div className="flex items-center gap-2 min-w-0">
+              <Badge variant="secondary" className="shrink-0">
+                {inspectedElement.type === "node" ? "Node" : "Relationship"}
+              </Badge>
+              <h3 className="text-sm font-semibold truncate">
+                {inspectedElement.type === "node"
+                  ? (inspectedElement.node.label ??
+                    inspectedElement.node.id ??
+                    "Node")
+                  : (inspectedElement.edge.label ?? "Relationship")}
+              </h3>
+            </div>
             <button
               onClick={() => setInspectedElement(null)}
               className="text-muted-foreground hover:text-foreground text-lg leading-none"
diff --git a/app/src/lib/chart-registry.ts b/app/src/lib/chart-registry.ts
index e0ea85d8..4b9b8e97 100644
--- a/app/src/lib/chart-registry.ts
+++ b/app/src/lib/chart-registry.ts
@@ -283,6 +283,7 @@ function transformToGraphData(data: unknown): unknown {
     if (!edgesMap.has(edgeId)) {
       const rawProps = (v.properties ?? {}) as Record<string, unknown>;
       edgesMap.set(edgeId, {
+        id: edgeId,
         source: String(v.startNodeElementId ?? v.start),
         target: String(v.endNodeElementId ?? v.end),
         label: String(v.type),
diff --git a/component/src/charts/types.ts b/component/src/charts/types.ts
index c0a4e345..75146d01 100644
--- a/component/src/charts/types.ts
+++ b/component/src/charts/types.ts
@@ -75,6 +75,7 @@ export interface GraphNode {
 }
 
 export interface GraphEdge {
+  id?: string;
   source: string;
   target: string;
   label?: string;

From 7c1f17fc3df3d5b7704e6545b5502caf0f47d0e1 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:44:14 +0200
Subject: [PATCH 07/36] feat: dual Y-axis support for line chart (#159)

Add rightAxisSeries prop to LineChart so series with different scales
can share the same chart. When rightAxisSeries is non-empty, yAxis
becomes an array [leftAxis, rightAxis] and each series gets
yAxisIndex 0 or 1 based on whether its name appears in the set.

Also adds a rightYAxisLabel prop for the secondary axis label, exposes
both options in the chart options panel as text inputs (comma-separated
for series names), and wires them through chart-renderer.

Closes #159
---
 app/src/components/chart-renderer.tsx         | 10 +++
 .../src/charts/__tests__/line-chart.test.tsx  | 63 +++++++++++++++++++
 component/src/charts/line-chart.tsx           | 43 ++++++++++---
 .../components/composed/chart-options/line.ts | 18 ++++++
 4 files changed, 126 insertions(+), 8 deletions(-)

diff --git a/app/src/components/chart-renderer.tsx b/app/src/components/chart-renderer.tsx
index 1514fc57..5293d6bd 100644
--- a/app/src/components/chart-renderer.tsx
+++ b/app/src/components/chart-renderer.tsx
@@ -230,6 +230,16 @@ function ChartRendererInner({
           colorThresholds={colorThresholds}
           stylingRules={stylingRules}
           paramValues={paramValues}
+          rightAxisSeries={
+            typeof settings.rightAxisSeries === "string" &&
+            settings.rightAxisSeries.trim() !== ""
+              ? settings.rightAxisSeries
+                  .split(",")
+                  .map((s) => s.trim())
+                  .filter(Boolean)
+              : undefined
+          }
+          rightYAxisLabel={settings.rightYAxisLabel as string | undefined}
           onClick={handleEChartsClick}
           enableDataZoom={settings.enableDataZoom as boolean | undefined}
           colorPalette={settings.colorPalette as string | undefined}
diff --git a/component/src/charts/__tests__/line-chart.test.tsx b/component/src/charts/__tests__/line-chart.test.tsx
index c33c2962..e834b8ab 100644
--- a/component/src/charts/__tests__/line-chart.test.tsx
+++ b/component/src/charts/__tests__/line-chart.test.tsx
@@ -263,4 +263,67 @@ describe("LineChart", () => {
     const optionsCall = mockSetOption.mock.calls[0][0];
     expect(optionsCall.xAxis.type).toBe("category");
   });
+
+  // --- Dual Y-axis ---
+
+  it("renders a single y-axis object when rightAxisSeries is empty or undefined", () => {
+    render(<LineChart data={multiSeriesData} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(Array.isArray(optionsCall.yAxis)).toBe(false);
+    expect(optionsCall.yAxis.type).toBe("value");
+  });
+
+  it("renders two y-axes when rightAxisSeries is non-empty", () => {
+    render(<LineChart data={multiSeriesData} rightAxisSeries={["cost"]} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(Array.isArray(optionsCall.yAxis)).toBe(true);
+    expect(optionsCall.yAxis).toHaveLength(2);
+    expect(optionsCall.yAxis[0].type).toBe("value");
+    expect(optionsCall.yAxis[1].type).toBe("value");
+  });
+
+  it("assigns yAxisIndex 0 to left series and 1 to right series", () => {
+    render(<LineChart data={multiSeriesData} rightAxisSeries={["cost"]} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].name).toBe("revenue");
+    expect(optionsCall.series[0].yAxisIndex).toBe(0);
+    expect(optionsCall.series[1].name).toBe("cost");
+    expect(optionsCall.series[1].yAxisIndex).toBe(1);
+  });
+
+  it("supports multiple series on the right axis", () => {
+    const data = [
+      { x: "Jan", a: 1, b: 2, c: 3 },
+      { x: "Feb", a: 4, b: 5, c: 6 },
+    ];
+    render(<LineChart data={data} rightAxisSeries={["b", "c"]} />);
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].yAxisIndex).toBe(0);
+    expect(optionsCall.series[1].yAxisIndex).toBe(1);
+    expect(optionsCall.series[2].yAxisIndex).toBe(1);
+  });
+
+  it("applies yAxisLabel to left axis and rightYAxisLabel to right axis", () => {
+    render(
+      <LineChart
+        data={multiSeriesData}
+        rightAxisSeries={["cost"]}
+        yAxisLabel="Revenue ($)"
+        rightYAxisLabel="Cost (%)"
+      />,
+    );
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.yAxis[0].name).toBe("Revenue ($)");
+    expect(optionsCall.yAxis[1].name).toBe("Cost (%)");
+  });
+
+  it("ignores unknown series names in rightAxisSeries (treats as left)", () => {
+    render(
+      <LineChart data={multiSeriesData} rightAxisSeries={["nonexistent"]} />,
+    );
+    const optionsCall = mockSetOption.mock.calls[0][0];
+    expect(optionsCall.series[0].yAxisIndex).toBe(0);
+    expect(optionsCall.series[1].yAxisIndex).toBe(0);
+    expect(Array.isArray(optionsCall.yAxis)).toBe(true);
+  });
 });
diff --git a/component/src/charts/line-chart.tsx b/component/src/charts/line-chart.tsx
index c2b5136e..76449cd1 100644
--- a/component/src/charts/line-chart.tsx
+++ b/component/src/charts/line-chart.tsx
@@ -46,6 +46,14 @@ export interface LineChartProps extends Omit<BaseChartProps, "options"> {
   stylingRules?: StylingRule[];
   /** Resolved parameter values for parameterRef comparisons */
   paramValues?: Record<string, unknown>;
+  /**
+   * Series names to render on a secondary (right) Y-axis. When non-empty,
+   * the chart renders two independent Y-axes so series with different
+   * scales can share the same chart.
+   */
+  rightAxisSeries?: string[];
+  /** Right Y-axis label (used when rightAxisSeries is non-empty) */
+  rightYAxisLabel?: string;
 }
 
 /**
@@ -72,6 +80,8 @@ function LineChart({
   colorThresholds,
   stylingRules,
   paramValues,
+  rightAxisSeries,
+  rightYAxisLabel,
   samplingThreshold = 1000,
   samplingMethod = "lttb",
   ...rest
@@ -95,6 +105,26 @@ function LineChart({
     const markLine = buildMarkLineFromRefs(refLines);
     const xValues = data.map((d) => d.x);
     const useTimeAxis = isTimeSeriesData(xValues);
+    const rightAxisSet = new Set(rightAxisSeries ?? []);
+    const useDualAxis = rightAxisSet.size > 0;
+
+    const leftYAxis = {
+      type: "value" as const,
+      name: compact ? undefined : yAxisLabel,
+      nameLocation: "middle" as const,
+      nameGap: 50,
+      axisLabel: { show: !compact },
+      splitLine: { show: showGridLines },
+    };
+    const rightYAxis = {
+      type: "value" as const,
+      name: compact ? undefined : rightYAxisLabel,
+      nameLocation: "middle" as const,
+      nameGap: 50,
+      axisLabel: { show: !compact },
+      // Only the left axis draws grid split lines to avoid visual clutter
+      splitLine: { show: false },
+    };
 
     return {
       tooltip: { trigger: "axis", formatter: buildTooltipFormatter() },
@@ -102,6 +132,7 @@ function LineChart({
       grid: {
         ...buildCompactGrid(compact, effectiveShowLegend),
         left: compact ? 8 : 48,
+        right: useDualAxis && !compact ? 56 : undefined,
       },
       xAxis: {
         type: useTimeAxis ? "time" : "category",
@@ -111,14 +142,7 @@ function LineChart({
         nameGap: 30,
         axisLabel: { show: !compact },
       },
-      yAxis: {
-        type: "value",
-        name: compact ? undefined : yAxisLabel,
-        nameLocation: "middle",
-        nameGap: 50,
-        axisLabel: { show: !compact },
-        splitLine: { show: showGridLines },
-      },
+      yAxis: useDualAxis ? [leftYAxis, rightYAxis] : leftYAxis,
       series: seriesKeys.map((key, idx) => {
         let lastValue: number | undefined;
         for (let i = data.length - 1; i >= 0; i -= 1) {
@@ -135,6 +159,7 @@ function LineChart({
         return {
           name: key,
           type: "line" as const,
+          yAxisIndex: useDualAxis && rightAxisSet.has(key) ? 1 : 0,
           data: useTimeAxis
             ? data.map((d) => [d.x, d[key]])
             : data.map((d) => d[key] as number),
@@ -169,6 +194,8 @@ function LineChart({
     colorThresholds,
     stylingRules,
     paramValues,
+    rightAxisSeries,
+    rightYAxisLabel,
     compact,
     hideLegend,
     samplingThreshold,
diff --git a/component/src/components/composed/chart-options/line.ts b/component/src/components/composed/chart-options/line.ts
index b4046183..fd750b6a 100644
--- a/component/src/components/composed/chart-options/line.ts
+++ b/component/src/components/composed/chart-options/line.ts
@@ -54,6 +54,24 @@ export const lineOptions: ChartOptionDef[] = [
   SHARED_SHOW_GRID_LINES,
   SHARED_X_AXIS_LABEL,
   SHARED_Y_AXIS_LABEL,
+  {
+    key: "rightAxisSeries",
+    label: "Right Y-Axis Series",
+    type: "text",
+    default: "",
+    category: "Labels",
+    description:
+      "Comma-separated series names to render on a secondary (right) Y-axis. Leave empty to use a single Y-axis.",
+  },
+  {
+    key: "rightYAxisLabel",
+    label: "Right Y-Axis Label",
+    type: "text",
+    default: "",
+    category: "Labels",
+    description:
+      "Custom label for the secondary Y-axis. Applies only when Right Y-Axis Series is non-empty.",
+  },
   SHARED_SHOW_LEGEND,
   SHARED_REFERENCE_LINES,
   {

From a42cd1a8b666a8e090446fee630ceb9d40bc462c Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:44:47 +0200
Subject: [PATCH 08/36] feat: select dropdown field type for form widget (#151)

Adds static options support for the form widget's select field type.
Users can now provide a comma-separated list of options (e.g.
'low,medium,high') instead of writing a seed query. When staticOptions
is set, it takes precedence over the seed query. Multi-select and
cascading-select still use seed queries only.

Closes #151
---
 app/src/components/form-widget-renderer.tsx   | 20 +++++++++++++++++--
 .../widget-editor/form-fields-editor.tsx      | 16 ++++++++++++++-
 app/src/lib/form-field-def.ts                 |  1 +
 package-lock.json                             |  1 +
 4 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/app/src/components/form-widget-renderer.tsx b/app/src/components/form-widget-renderer.tsx
index f312827c..4641b1c4 100644
--- a/app/src/components/form-widget-renderer.tsx
+++ b/app/src/components/form-widget-renderer.tsx
@@ -75,8 +75,22 @@ function FieldInput({
     [field.parentParameterName, parentValue],
   );
 
+  const hasStaticOptions =
+    field.parameterType === "select" &&
+    !!field.staticOptions &&
+    field.staticOptions.trim().length > 0;
+
+  const staticOptionsList = useMemo(() => {
+    if (!hasStaticOptions) return [];
+    return (field.staticOptions ?? "")
+      .split(",")
+      .map((o) => o.trim())
+      .filter((o) => o.length > 0)
+      .map((o) => ({ value: o, label: o }));
+  }, [hasStaticOptions, field.staticOptions]);
+
   const needsSeed =
-    field.parameterType === "select" ||
+    (field.parameterType === "select" && !hasStaticOptions) ||
     field.parameterType === "multi-select" ||
     field.parameterType === "cascading-select";
 
@@ -92,7 +106,7 @@ function FieldInput({
     return Object.keys(base).length > 0 ? base : undefined;
   }, [field.parameterType, field.searchable, parentParams, debouncedSearch]);
 
-  const { options, loading } = useSeedQuery(
+  const { options: seedOptions, loading } = useSeedQuery(
     connectionId,
     field.seedQuery,
     needsSeed && cascadingEnabled,
@@ -100,6 +114,8 @@ function FieldInput({
     tenantId,
   );
 
+  const options = hasStaticOptions ? staticOptionsList : seedOptions;
+
   // Clear cascading child when parent changes
   const prevParentValue = useRef(parentValue);
   useEffect(() => {
diff --git a/app/src/components/widget-editor/form-fields-editor.tsx b/app/src/components/widget-editor/form-fields-editor.tsx
index 301a1750..fe06eb46 100644
--- a/app/src/components/widget-editor/form-fields-editor.tsx
+++ b/app/src/components/widget-editor/form-fields-editor.tsx
@@ -201,10 +201,24 @@ function SortableFieldItem({
           </Select>
         </div>
 
+        {/* Static options (for select only) */}
+        {field.parameterType === "select" && (
+          <LabeledInput
+            label="Static Options (comma-separated)"
+            value={field.staticOptions ?? ""}
+            onChange={(v) => onUpdate(field.id, { staticOptions: v })}
+            placeholder="e.g. low,medium,high"
+          />
+        )}
+
         {/* Seed query (for select/multi-select/cascading-select) */}
         {needsSeedQuery(field.parameterType) && (
           <div className="space-y-1.5">
-            <Label className="text-xs">Options Query</Label>
+            <Label className="text-xs">
+              Options Query{" "}
+              {field.parameterType === "select" &&
+                "(ignored if static options set)"}
+            </Label>
             <Textarea
               value={field.seedQuery ?? ""}
               onChange={(e) =>
diff --git a/app/src/lib/form-field-def.ts b/app/src/lib/form-field-def.ts
index 8f49b15a..68e01400 100644
--- a/app/src/lib/form-field-def.ts
+++ b/app/src/lib/form-field-def.ts
@@ -7,6 +7,7 @@ export interface FormFieldDef {
   parameterType: ParameterType; // all 8 types
   required?: boolean; // when false, empty value passes null to the query instead of being omitted
   seedQuery?: string; // for select/multi-select/cascading-select
+  staticOptions?: string; // for select: comma-separated static options (e.g. "low,medium,high")
   parentParameterName?: string; // for cascading-select
   rangeMin?: number; // for number-range
   rangeMax?: number;
diff --git a/package-lock.json b/package-lock.json
index aedac1c9..a79003c7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5,6 +5,7 @@
   "packages": {
     "": {
       "name": "neoboard",
+      "license": "Elastic-2.0",
       "devDependencies": {
         "@eslint/js": "^9.39.1",
         "@next/eslint-plugin-next": "^16.2.1",

From 4d6c357172967ccd670a3ce3bd36fb4f5012cb6c Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:44:58 +0200
Subject: [PATCH 09/36] feat: onboarding guide on empty dashboards page (#333)

Replace the minimal EmptyState on the dashboards page with a welcoming
Getting Started guide for first-time users. Shows a welcome message, a
prominent "Create your first dashboard" CTA, a link to the docs, and a
three-step guide (connect, create, add widgets) with deep links to the
relevant pages.

Closes #333

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/src/app/(dashboard)/page.tsx | 297 ++++++++++++++++++++++++-------
 1 file changed, 231 insertions(+), 66 deletions(-)

diff --git a/app/src/app/(dashboard)/page.tsx b/app/src/app/(dashboard)/page.tsx
index 52f6b80f..40576114 100644
--- a/app/src/app/(dashboard)/page.tsx
+++ b/app/src/app/(dashboard)/page.tsx
@@ -3,6 +3,7 @@
 import { useRef, useState } from "react";
 import { useRouter } from "next/navigation";
 import { useSession } from "next-auth/react";
+import Link from "next/link";
 import {
   Plus,
   LayoutDashboard,
@@ -14,6 +15,10 @@ import {
   Globe,
   Upload,
   Download,
+  Database,
+  BarChart3,
+  BookOpen,
+  ArrowRight,
 } from "lucide-react";
 import {
   useDashboards,
@@ -103,7 +108,10 @@ interface ImportDashboardDialogProps {
   readonly onOpenChange: (open: boolean) => void;
 }
 
-function ImportDashboardDialog({ open, onOpenChange }: ImportDashboardDialogProps) {
+function ImportDashboardDialog({
+  open,
+  onOpenChange,
+}: ImportDashboardDialogProps) {
   const router = useRouter();
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [parsed, setParsed] = useState<ParsedImport | null>(null);
@@ -138,39 +146,47 @@ function ImportDashboardDialog({ open, onOpenChange }: ImportDashboardDialogProp
 
       if (isNeoDashFormat(json)) {
         // NeoDash — no connection mapping needed
-        const widgetCount = (json.pages as Array<{ reports?: unknown[] }>)?.reduce(
-          (sum: number, p) => sum + (p.reports?.length ?? 0),
-          0
-        ) ?? 0;
+        const widgetCount =
+          (json.pages as Array<{ reports?: unknown[] }>)?.reduce(
+            (sum: number, p) => sum + (p.reports?.length ?? 0),
+            0,
+          ) ?? 0;
         setParsed({
           payload: json,
-          dashboardName: (json as { title?: string }).title ?? "Imported Dashboard",
+          dashboardName:
+            (json as { title?: string }).title ?? "Imported Dashboard",
           widgetCount: widgetCount,
           isNeoDash: true,
           connections: {},
         });
       } else if (json.formatVersion === 1) {
-          // NeoBoard export
-          const connections = (json.connections ?? {}) as Record<string, ConnectionInfo>;
-          const widgetCount = (json.layout?.pages as Array<{ widgets?: unknown[] }>)?.reduce(
+        // NeoBoard export
+        const connections = (json.connections ?? {}) as Record<
+          string,
+          ConnectionInfo
+        >;
+        const widgetCount =
+          (json.layout?.pages as Array<{ widgets?: unknown[] }>)?.reduce(
             (sum: number, p) => sum + (p.widgets?.length ?? 0),
-            0
+            0,
           ) ?? 0;
-          const initialMapping: Record<string, string> = {};
-          for (const key of Object.keys(connections)) {
-            initialMapping[key] = "";
-          }
-          setMapping(initialMapping);
-          setParsed({
-            payload: json,
-            dashboardName: json.dashboard?.name ?? "Imported Dashboard",
-            widgetCount,
-            isNeoDash: false,
-            connections,
-          });
-        } else {
-          setFileError("Unrecognised file format. Expected a NeoBoard or NeoDash export.");
+        const initialMapping: Record<string, string> = {};
+        for (const key of Object.keys(connections)) {
+          initialMapping[key] = "";
         }
+        setMapping(initialMapping);
+        setParsed({
+          payload: json,
+          dashboardName: json.dashboard?.name ?? "Imported Dashboard",
+          widgetCount,
+          isNeoDash: false,
+          connections,
+        });
+      } else {
+        setFileError(
+          "Unrecognised file format. Expected a NeoBoard or NeoDash export.",
+        );
+      }
     } catch {
       setFileError("Failed to parse file. Make sure it is a valid JSON file.");
     }
@@ -188,14 +204,16 @@ function ImportDashboardDialog({ open, onOpenChange }: ImportDashboardDialogProp
       handleOpenChange(false);
       router.push(`/${result.id}`);
     } catch (error) {
-      setFileError(error instanceof Error ? error.message : "Failed to import dashboard.");
+      setFileError(
+        error instanceof Error ? error.message : "Failed to import dashboard.",
+      );
     }
   }
 
-  const hasConnections = parsed && !parsed.isNeoDash && Object.keys(parsed.connections).length > 0;
+  const hasConnections =
+    parsed && !parsed.isNeoDash && Object.keys(parsed.connections).length > 0;
   const allMapped =
-    !hasConnections ||
-    Object.values(mapping).every((v) => v !== "");
+    !hasConnections || Object.values(mapping).every((v) => v !== "");
 
   return (
     <Dialog open={open} onOpenChange={handleOpenChange}>
@@ -223,10 +241,15 @@ function ImportDashboardDialog({ open, onOpenChange }: ImportDashboardDialogProp
 
             {parsed && (
               <div className="rounded-md border p-3 bg-muted/40 space-y-1">
-                <p className="text-sm font-medium truncate">{parsed.dashboardName}</p>
+                <p className="text-sm font-medium truncate">
+                  {parsed.dashboardName}
+                </p>
                 <p className="text-xs text-muted-foreground">
-                  {parsed.widgetCount} widget{parsed.widgetCount === 1 ? "" : "s"}
-                  {parsed.isNeoDash ? " · NeoDash format" : " · NeoBoard format"}
+                  {parsed.widgetCount} widget
+                  {parsed.widgetCount === 1 ? "" : "s"}
+                  {parsed.isNeoDash
+                    ? " · NeoDash format"
+                    : " · NeoBoard format"}
                 </p>
               </div>
             )}
@@ -237,12 +260,21 @@ function ImportDashboardDialog({ open, onOpenChange }: ImportDashboardDialogProp
                   Map each connection placeholder to a local connection:
                 </p>
                 {Object.entries(parsed.connections).map(([key, info]) => {
-                  const compatible = availableConnections.filter((c) => c.type === info.type);
+                  const compatible = availableConnections.filter(
+                    (c) => c.type === info.type,
+                  );
                   return (
-                    <div key={key} className="grid grid-cols-2 gap-2 items-center">
+                    <div
+                      key={key}
+                      className="grid grid-cols-2 gap-2 items-center"
+                    >
                       <div className="min-w-0">
-                        <p className="text-sm font-medium truncate">{info.name}</p>
-                        <p className="text-xs text-muted-foreground">{info.type}</p>
+                        <p className="text-sm font-medium truncate">
+                          {info.name}
+                        </p>
+                        <p className="text-xs text-muted-foreground">
+                          {info.type}
+                        </p>
                       </div>
                       <Select
                         value={mapping[key] ?? ""}
@@ -297,6 +329,125 @@ function ImportDashboardDialog({ open, onOpenChange }: ImportDashboardDialogProp
   );
 }
 
+// ── GettingStartedGuide ──────────────────────────────────────────────
+
+interface GettingStartedGuideProps {
+  readonly onCreateDashboard: () => void;
+}
+
+function GettingStartedGuide({ onCreateDashboard }: GettingStartedGuideProps) {
+  return (
+    <div className="mx-auto max-w-4xl">
+      <div className="rounded-lg border bg-card p-8 text-center">
+        <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+          <LayoutDashboard className="h-6 w-6" />
+        </div>
+        <h2 className="text-2xl font-semibold">Welcome to NeoBoard</h2>
+        <p className="mx-auto mt-2 max-w-xl text-sm text-muted-foreground">
+          Build dashboards that connect to your Neo4j and PostgreSQL databases.
+          Get started in three simple steps.
+        </p>
+        <div className="mt-6 flex flex-wrap items-center justify-center gap-3">
+          <Button size="lg" onClick={onCreateDashboard}>
+            <Plus className="mr-2 h-4 w-4" />
+            Create your first dashboard
+          </Button>
+          <Button variant="outline" size="lg" asChild>
+            <a
+              href="https://neoboard.app/docs/getting-started/quick-start/"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              <BookOpen className="mr-2 h-4 w-4" />
+              Read the docs
+            </a>
+          </Button>
+        </div>
+      </div>
+
+      <div className="mt-6 grid gap-4 sm:grid-cols-3">
+        <Card>
+          <CardHeader>
+            <div className="mb-2 flex h-8 w-8 items-center justify-center rounded-md bg-primary/10 text-primary">
+              <Database className="h-4 w-4" />
+            </div>
+            <CardTitle className="text-base">
+              <span className="mr-2 text-muted-foreground">1.</span>
+              Add a connection
+            </CardTitle>
+            <CardDescription>
+              Connect to your Neo4j or PostgreSQL database so NeoBoard can query
+              your data.
+            </CardDescription>
+          </CardHeader>
+          <CardFooter>
+            <Link
+              href="/connections"
+              className="inline-flex items-center text-sm font-medium text-primary hover:underline"
+            >
+              Go to Connections
+              <ArrowRight className="ml-1 h-3.5 w-3.5" />
+            </Link>
+          </CardFooter>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <div className="mb-2 flex h-8 w-8 items-center justify-center rounded-md bg-primary/10 text-primary">
+              <LayoutDashboard className="h-4 w-4" />
+            </div>
+            <CardTitle className="text-base">
+              <span className="mr-2 text-muted-foreground">2.</span>
+              Create a dashboard
+            </CardTitle>
+            <CardDescription>
+              Give your dashboard a name and pick the layout that fits your
+              story.
+            </CardDescription>
+          </CardHeader>
+          <CardFooter>
+            <button
+              type="button"
+              onClick={onCreateDashboard}
+              className="inline-flex items-center text-sm font-medium text-primary hover:underline"
+            >
+              New dashboard
+              <ArrowRight className="ml-1 h-3.5 w-3.5" />
+            </button>
+          </CardFooter>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <div className="mb-2 flex h-8 w-8 items-center justify-center rounded-md bg-primary/10 text-primary">
+              <BarChart3 className="h-4 w-4" />
+            </div>
+            <CardTitle className="text-base">
+              <span className="mr-2 text-muted-foreground">3.</span>
+              Add widgets
+            </CardTitle>
+            <CardDescription>
+              Write a Cypher or SQL query, pick a chart type, and visualize your
+              results.
+            </CardDescription>
+          </CardHeader>
+          <CardFooter>
+            <a
+              href="https://neoboard.app/docs/guides/widgets/"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center text-sm font-medium text-primary hover:underline"
+            >
+              Widget guide
+              <ArrowRight className="ml-1 h-3.5 w-3.5" />
+            </a>
+          </CardFooter>
+        </Card>
+      </div>
+    </div>
+  );
+}
+
 // ── Main page ─────────────────────────────────────────────────────────
 
 export default function DashboardListPage() {
@@ -404,23 +555,17 @@ export default function DashboardListPage() {
       <div className="mt-6">
         <LoadingOverlay loading={isLoading} text="Loading dashboards...">
           {!dashboardList?.length ? (
-            <EmptyState
-              icon={<LayoutDashboard className="h-12 w-12" />}
-              title="No dashboards yet"
-              description={
-                canCreate
-                  ? "Create your first dashboard to start visualizing your data."
-                  : "No dashboards have been assigned to you yet."
-              }
-              action={
-                canCreate ? (
-                  <Button onClick={() => setShowCreate(true)}>
-                    <Plus className="mr-2 h-4 w-4" />
-                    Create your first dashboard
-                  </Button>
-                ) : undefined
-              }
-            />
+            canCreate ? (
+              <GettingStartedGuide
+                onCreateDashboard={() => setShowCreate(true)}
+              />
+            ) : (
+              <EmptyState
+                icon={<LayoutDashboard className="h-12 w-12" />}
+                title="No dashboards yet"
+                description="No dashboards have been assigned to you yet."
+              />
+            )
           ) : (
             <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
               {dashboardList.map((d) => {
@@ -428,8 +573,7 @@ export default function DashboardListPage() {
                   d.role === "owner" ||
                   d.role === "editor" ||
                   d.role === "admin";
-                const canDelete =
-                  d.role === "owner" || d.role === "admin";
+                const canDelete = d.role === "owner" || d.role === "admin";
                 const canDuplicate = systemRole !== "reader";
 
                 return (
@@ -440,7 +584,9 @@ export default function DashboardListPage() {
                   >
                     <CardHeader className="pb-2">
                       <div className="flex items-start justify-between gap-2">
-                        <CardTitle className="text-base truncate">{d.name}</CardTitle>
+                        <CardTitle className="text-base truncate">
+                          {d.name}
+                        </CardTitle>
                         <div className="flex items-center gap-1 shrink-0">
                           {(canEdit || canDuplicate || canDelete) && (
                             <DropdownMenu>
@@ -452,19 +598,28 @@ export default function DashboardListPage() {
                                   onClick={(e) => e.stopPropagation()}
                                 >
                                   <MoreVertical className="h-4 w-4" />
-                                  <span className="sr-only">Dashboard options</span>
+                                  <span className="sr-only">
+                                    Dashboard options
+                                  </span>
                                 </Button>
                               </DropdownMenuTrigger>
-                              <DropdownMenuContent align="end" onClick={(e) => e.stopPropagation()}>
+                              <DropdownMenuContent
+                                align="end"
+                                onClick={(e) => e.stopPropagation()}
+                              >
                                 {canEdit && (
-                                  <DropdownMenuItem onClick={() => router.push(`/${d.id}/edit`)}>
+                                  <DropdownMenuItem
+                                    onClick={() => router.push(`/${d.id}/edit`)}
+                                  >
                                     <Pencil className="mr-2 h-4 w-4" />
                                     Edit
                                   </DropdownMenuItem>
                                 )}
                                 {canDuplicate && (
                                   <DropdownMenuItem
-                                    onClick={() => duplicateDashboard.mutate(d.id)}
+                                    onClick={() =>
+                                      duplicateDashboard.mutate(d.id)
+                                    }
                                     disabled={duplicateDashboard.isPending}
                                   >
                                     <Copy className="mr-2 h-4 w-4" />
@@ -473,9 +628,11 @@ export default function DashboardListPage() {
                                 )}
                                 <DropdownMenuItem
                                   onClick={() => {
-                                    void triggerExport(d.id, d.name).catch((err) => {
-                                      console.error("Export failed", err);
-                                    });
+                                    void triggerExport(d.id, d.name).catch(
+                                      (err) => {
+                                        console.error("Export failed", err);
+                                      },
+                                    );
                                   }}
                                 >
                                   <Download className="mr-2 h-4 w-4" />
@@ -497,13 +654,18 @@ export default function DashboardListPage() {
                             </DropdownMenu>
                           )}
                           {d.isPublic && (
-                            <Globe className="h-3.5 w-3.5 text-muted-foreground" aria-label="Public" />
+                            <Globe
+                              className="h-3.5 w-3.5 text-muted-foreground"
+                              aria-label="Public"
+                            />
                           )}
                           <Badge variant="secondary">{d.role}</Badge>
                         </div>
                       </div>
                       {d.description && (
-                        <CardDescription className="line-clamp-2">{d.description}</CardDescription>
+                        <CardDescription className="line-clamp-2">
+                          {d.description}
+                        </CardDescription>
                       )}
                     </CardHeader>
                     <CardContent className="flex-1 p-4 pt-0">
@@ -512,11 +674,14 @@ export default function DashboardListPage() {
                     <CardFooter className="pt-0 text-xs text-muted-foreground justify-between">
                       <span className="flex items-center gap-1 truncate">
                         <TimeAgo date={d.updatedAt} />
-                        {d.updatedByName && <span className="truncate">by {d.updatedByName}</span>}
+                        {d.updatedByName && (
+                          <span className="truncate">by {d.updatedByName}</span>
+                        )}
                       </span>
                       <span className="flex items-center gap-1 shrink-0">
                         <Grid2X2 className="h-3 w-3" />
-                        {d.widgetCount ?? 0} widget{(d.widgetCount ?? 0) !== 1 ? "s" : ""}
+                        {d.widgetCount ?? 0} widget
+                        {(d.widgetCount ?? 0) !== 1 ? "s" : ""}
                       </span>
                     </CardFooter>
                   </Card>

From bc6bb7668bf07feaf1f902661dd760f2ca921c27 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:48:31 +0200
Subject: [PATCH 10/36] feat: field validation for form widget (#150)

---
 app/src/components/form-widget-renderer.tsx   |  42 +++--
 .../widget-editor/form-fields-editor.tsx      |  30 +++-
 .../__tests__/form-field-validation.test.ts   | 155 ++++++++++++++++++
 app/src/lib/form-field-def.ts                 |   8 +
 app/src/lib/form-field-validation.ts          |  66 ++++++++
 5 files changed, 286 insertions(+), 15 deletions(-)
 create mode 100644 app/src/lib/__tests__/form-field-validation.test.ts
 create mode 100644 app/src/lib/form-field-validation.ts

diff --git a/app/src/components/form-widget-renderer.tsx b/app/src/components/form-widget-renderer.tsx
index f312827c..b32919d0 100644
--- a/app/src/components/form-widget-renderer.tsx
+++ b/app/src/components/form-widget-renderer.tsx
@@ -26,6 +26,7 @@ import { useWriteQueryExecution } from "@/hooks/use-write-query-execution";
 import { useSeedQuery } from "@/hooks/use-seed-query";
 import { buildFormParams } from "@/lib/form-field-def";
 import type { FormFieldDef } from "@/lib/form-field-def";
+import { validateFieldValue } from "@/lib/form-field-validation";
 import { DebouncedTextInput } from "./debounced-text-input";
 
 export interface FormWidgetRendererProps {
@@ -374,26 +375,35 @@ export function FormWidgetRenderer({
     });
   }, []);
 
+  const handleFieldBlur = useCallback(
+    (field: FormFieldDef) => {
+      const error = validateFieldValue(field, localValues[field.parameterName]);
+      setFieldErrors((prev) => {
+        if (error) {
+          if (prev[field.parameterName] === error) return prev;
+          return { ...prev, [field.parameterName]: error };
+        }
+        if (!prev[field.parameterName]) return prev;
+        const next = { ...prev };
+        delete next[field.parameterName];
+        return next;
+      });
+    },
+    [localValues],
+  );
+
   const writeQuery = useWriteQueryExecution();
 
   const handleSubmit = useCallback(() => {
     setSuccessMessage(null);
     setErrorMessage(null);
 
-    // Validate required fields
+    // Validate required + validationType for all fields
     const errors: Record<string, string> = {};
     for (const field of fields) {
-      if (field.required) {
-        const v = localValues[field.parameterName];
-        let isEmpty = v === undefined || v === null || v === "";
-        if (!isEmpty && Array.isArray(v)) isEmpty = v.length === 0;
-        if (!isEmpty && field.parameterType === "date-range") {
-          const r = v as { from?: string; to?: string } | undefined;
-          isEmpty = !r?.from && !r?.to;
-        }
-        if (isEmpty) {
-          errors[field.parameterName] = "This field is required";
-        }
+      const error = validateFieldValue(field, localValues[field.parameterName]);
+      if (error) {
+        errors[field.parameterName] = error;
       }
     }
 
@@ -455,7 +465,11 @@ export function FormWidgetRenderer({
         className="space-y-4 p-4"
       >
         {fields.map((field) => (
-          <div key={field.id} className="space-y-1.5">
+          <div
+            key={field.id}
+            className="space-y-1.5"
+            onBlur={() => handleFieldBlur(field)}
+          >
             <Label htmlFor={`form-field-${field.parameterName}`}>
               {field.label || field.parameterName}
               {field.required && (
@@ -487,7 +501,7 @@ export function FormWidgetRenderer({
 
         <Button
           type="submit"
-          disabled={writeQuery.isPending}
+          disabled={writeQuery.isPending || Object.keys(fieldErrors).length > 0}
           className="w-full"
         >
           {writeQuery.isPending
diff --git a/app/src/components/widget-editor/form-fields-editor.tsx b/app/src/components/widget-editor/form-fields-editor.tsx
index 301a1750..05aeebb0 100644
--- a/app/src/components/widget-editor/form-fields-editor.tsx
+++ b/app/src/components/widget-editor/form-fields-editor.tsx
@@ -36,7 +36,10 @@ import {
   verticalListSortingStrategy,
 } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
-import type { FormFieldDef } from "@/lib/form-field-def";
+import type {
+  FormFieldDef,
+  FormFieldValidationType,
+} from "@/lib/form-field-def";
 import type { ParameterType } from "@/stores/parameter-store";
 import { useAccordionCrud } from "./use-accordion-crud";
 
@@ -263,6 +266,31 @@ function SortableFieldItem({
           />
         )}
 
+        {/* Validation Type (text inputs only) */}
+        {field.parameterType === "text" && (
+          <div className="space-y-1.5">
+            <Label className="text-xs">Validation</Label>
+            <Select
+              value={field.validationType ?? "text"}
+              onValueChange={(v) =>
+                onUpdate(field.id, {
+                  validationType: v as FormFieldValidationType,
+                })
+              }
+            >
+              <SelectTrigger className="h-7 text-xs">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="text">None (any text)</SelectItem>
+                <SelectItem value="number">Number</SelectItem>
+                <SelectItem value="email">Email</SelectItem>
+                <SelectItem value="date">Date</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+        )}
+
         {/* Required toggle */}
         <div className="flex items-center gap-2 pt-1">
           <Checkbox
diff --git a/app/src/lib/__tests__/form-field-validation.test.ts b/app/src/lib/__tests__/form-field-validation.test.ts
new file mode 100644
index 00000000..bdb7c9dd
--- /dev/null
+++ b/app/src/lib/__tests__/form-field-validation.test.ts
@@ -0,0 +1,155 @@
+import { describe, it, expect } from "vitest";
+import { validateFieldValue } from "../form-field-validation";
+import type { FormFieldDef } from "../form-field-def";
+
+describe("validateFieldValue", () => {
+  const baseField: FormFieldDef = {
+    id: "1",
+    label: "Field",
+    parameterName: "field",
+    parameterType: "text",
+  };
+
+  describe("required validation", () => {
+    it("returns error when required field is empty string", () => {
+      const field: FormFieldDef = { ...baseField, required: true };
+      expect(validateFieldValue(field, "")).toBe("This field is required");
+    });
+
+    it("returns error when required field is undefined", () => {
+      const field: FormFieldDef = { ...baseField, required: true };
+      expect(validateFieldValue(field, undefined)).toBe(
+        "This field is required",
+      );
+    });
+
+    it("returns error when required field is null", () => {
+      const field: FormFieldDef = { ...baseField, required: true };
+      expect(validateFieldValue(field, null)).toBe("This field is required");
+    });
+
+    it("returns error when required field is an empty array", () => {
+      const field: FormFieldDef = {
+        ...baseField,
+        parameterType: "multi-select",
+        required: true,
+      };
+      expect(validateFieldValue(field, [])).toBe("This field is required");
+    });
+
+    it("returns error when required date-range has no from and no to", () => {
+      const field: FormFieldDef = {
+        ...baseField,
+        parameterType: "date-range",
+        required: true,
+      };
+      expect(validateFieldValue(field, { from: "", to: "" })).toBe(
+        "This field is required",
+      );
+      expect(validateFieldValue(field, {})).toBe("This field is required");
+    });
+
+    it("returns null when required field has a value", () => {
+      const field: FormFieldDef = { ...baseField, required: true };
+      expect(validateFieldValue(field, "hello")).toBeNull();
+    });
+
+    it("returns null when optional field is empty", () => {
+      const field: FormFieldDef = { ...baseField, required: false };
+      expect(validateFieldValue(field, "")).toBeNull();
+      expect(validateFieldValue(field, undefined)).toBeNull();
+    });
+  });
+
+  describe("number validation", () => {
+    it("returns error when value is not numeric", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "number" };
+      expect(validateFieldValue(field, "abc")).toBe("Must be a valid number");
+    });
+
+    it("returns null when value is a numeric string", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "number" };
+      expect(validateFieldValue(field, "42")).toBeNull();
+      expect(validateFieldValue(field, "3.14")).toBeNull();
+      expect(validateFieldValue(field, "-7")).toBeNull();
+    });
+
+    it("returns null when value is empty and field is optional", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "number" };
+      expect(validateFieldValue(field, "")).toBeNull();
+    });
+
+    it("returns required error when empty and required takes precedence", () => {
+      const field: FormFieldDef = {
+        ...baseField,
+        validationType: "number",
+        required: true,
+      };
+      expect(validateFieldValue(field, "")).toBe("This field is required");
+    });
+  });
+
+  describe("email validation", () => {
+    it("returns error for invalid email strings", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "email" };
+      expect(validateFieldValue(field, "not-an-email")).toBe(
+        "Must be a valid email address",
+      );
+      expect(validateFieldValue(field, "foo@")).toBe(
+        "Must be a valid email address",
+      );
+      expect(validateFieldValue(field, "@bar.com")).toBe(
+        "Must be a valid email address",
+      );
+      expect(validateFieldValue(field, "foo @bar.com")).toBe(
+        "Must be a valid email address",
+      );
+    });
+
+    it("returns null for valid email addresses", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "email" };
+      expect(validateFieldValue(field, "user@example.com")).toBeNull();
+      expect(
+        validateFieldValue(field, "first.last+tag@sub.example.co"),
+      ).toBeNull();
+    });
+
+    it("returns null when empty and optional", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "email" };
+      expect(validateFieldValue(field, "")).toBeNull();
+    });
+  });
+
+  describe("date validation", () => {
+    it("returns error for unparseable dates", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "date" };
+      expect(validateFieldValue(field, "not-a-date")).toBe(
+        "Must be a valid date",
+      );
+    });
+
+    it("returns null for valid dates", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "date" };
+      expect(validateFieldValue(field, "2024-01-15")).toBeNull();
+      expect(validateFieldValue(field, "2024-12-31T23:59:59Z")).toBeNull();
+    });
+
+    it("returns null when empty and optional", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "date" };
+      expect(validateFieldValue(field, "")).toBeNull();
+    });
+  });
+
+  describe("text validation", () => {
+    it("returns null for any non-empty text when no validationType set", () => {
+      const field: FormFieldDef = { ...baseField };
+      expect(validateFieldValue(field, "hello world")).toBeNull();
+    });
+
+    it("returns null for non-validated fields without required", () => {
+      const field: FormFieldDef = { ...baseField, validationType: "text" };
+      expect(validateFieldValue(field, "anything")).toBeNull();
+      expect(validateFieldValue(field, "")).toBeNull();
+    });
+  });
+});
diff --git a/app/src/lib/form-field-def.ts b/app/src/lib/form-field-def.ts
index 8f49b15a..9c86e2c2 100644
--- a/app/src/lib/form-field-def.ts
+++ b/app/src/lib/form-field-def.ts
@@ -1,11 +1,19 @@
 import type { ParameterType } from "@/stores/parameter-store";
 
+/**
+ * Optional type-based validation applied to a field's value on blur.
+ * Independent from `parameterType` (the widget shape) so a free-form `text`
+ * input can still validate as a number, email, or date.
+ */
+export type FormFieldValidationType = "text" | "number" | "email" | "date";
+
 export interface FormFieldDef {
   id: string;
   label: string;
   parameterName: string; // without $param_ prefix
   parameterType: ParameterType; // all 8 types
   required?: boolean; // when false, empty value passes null to the query instead of being omitted
+  validationType?: FormFieldValidationType; // blur-time value validation
   seedQuery?: string; // for select/multi-select/cascading-select
   parentParameterName?: string; // for cascading-select
   rangeMin?: number; // for number-range
diff --git a/app/src/lib/form-field-validation.ts b/app/src/lib/form-field-validation.ts
new file mode 100644
index 00000000..48376c84
--- /dev/null
+++ b/app/src/lib/form-field-validation.ts
@@ -0,0 +1,66 @@
+import type { FormFieldDef } from "./form-field-def";
+
+/**
+ * Regex for validating an email address. Requires a non-empty local part, an
+ * "@", a non-empty domain, a dot, and a non-empty TLD with no whitespace.
+ */
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Determine whether a field's current value should be treated as "empty". */
+function isEmptyValue(field: FormFieldDef, value: unknown): boolean {
+  if (value === undefined || value === null || value === "") return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (field.parameterType === "date-range" && typeof value === "object") {
+    const r = value as { from?: string; to?: string };
+    return !r.from && !r.to;
+  }
+  return false;
+}
+
+/**
+ * Validate a single field's value. Returns an error message string when the
+ * value is invalid, or `null` when it is valid.
+ *
+ * Rules (in order):
+ *  1. If the field is required and empty, report required error.
+ *  2. If the value is empty and not required, no error.
+ *  3. Otherwise apply the field's `validationType` (number / email / date).
+ */
+export function validateFieldValue(
+  field: FormFieldDef,
+  value: unknown,
+): string | null {
+  const empty = isEmptyValue(field, value);
+
+  if (field.required && empty) {
+    return "This field is required";
+  }
+
+  if (empty) return null;
+
+  const validationType = field.validationType ?? "text";
+  if (validationType === "text") return null;
+
+  const stringValue = typeof value === "string" ? value : String(value);
+
+  switch (validationType) {
+    case "number": {
+      if (stringValue.trim() === "") return null;
+      return Number.isNaN(Number(stringValue))
+        ? "Must be a valid number"
+        : null;
+    }
+    case "email": {
+      return EMAIL_REGEX.test(stringValue)
+        ? null
+        : "Must be a valid email address";
+    }
+    case "date": {
+      return Number.isNaN(Date.parse(stringValue))
+        ? "Must be a valid date"
+        : null;
+    }
+    default:
+      return null;
+  }
+}

From ec6360ebbad0faf7c4c427820b979245469a2158 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 13:52:24 +0200
Subject: [PATCH 11/36] perf: memoize graph callbacks and consolidate state
 updates (#353)

---
 .../components/graph-exploration-wrapper.tsx  | 66 +++++++++++++------
 component/src/charts/graph-chart.tsx          | 11 +++-
 component/src/hooks/useGraphExploration.ts    | 47 +++++++++----
 3 files changed, 90 insertions(+), 34 deletions(-)

diff --git a/app/src/components/graph-exploration-wrapper.tsx b/app/src/components/graph-exploration-wrapper.tsx
index 91c5cde3..9429220f 100644
--- a/app/src/components/graph-exploration-wrapper.tsx
+++ b/app/src/components/graph-exploration-wrapper.tsx
@@ -243,6 +243,48 @@ export function GraphExplorationWrapper({
     setMenu({ node: e.node, x, y });
   }, []);
 
+  // Keep a ref to the current exploration value so handleNodeSelect stays
+  // stable across renders even as exploration.nodes / selection change.
+  // Without this, the inline callback would be rebuilt every render,
+  // causing GraphChart to see a new prop identity each time.
+  const explorationRef = useRef(exploration);
+  explorationRef.current = exploration;
+
+  const handleNodeSelect = useCallback(
+    (ids: string[]) => {
+      explorationRef.current.onNodeSelect(ids);
+      if (onChartClick && ids.length) {
+        onChartClick({ nodeId: ids[0] });
+      }
+      // Open property panel on single-click
+      if (ids.length === 1) {
+        const node = explorationRef.current.nodes.find((n) => n.id === ids[0]);
+        if (node) setInspectedElement({ type: "node", node });
+      } else {
+        setInspectedElement(null);
+      }
+    },
+    [onChartClick],
+  );
+
+  const handleRelationshipClick = useCallback((event: { edge: GraphEdge }) => {
+    setInspectedElement({ type: "edge", edge: event.edge });
+  }, []);
+
+  const handleLayoutChange = useCallback(
+    (layout: "force" | "circular" | "hierarchical") => {
+      storeSetState(widgetId, { layout });
+    },
+    [storeSetState, widgetId],
+  );
+
+  const handleCaptionMapChange = useCallback(
+    (captionMap: Record<string, string>) => {
+      storeSetState(widgetId, { captionMap });
+    },
+    [storeSetState, widgetId],
+  );
+
   return (
     <div
       ref={containerRef}
@@ -253,31 +295,15 @@ export function GraphExplorationWrapper({
         nodes={exploration.nodes}
         edges={exploration.edges}
         selectedNodeIds={exploration.selectedNodeIds}
-        onNodeSelect={(ids) => {
-          exploration.onNodeSelect(ids);
-          if (onChartClick && ids.length) {
-            onChartClick({ nodeId: ids[0] });
-          }
-          // Open property panel on single-click
-          if (ids.length === 1) {
-            const node = exploration.nodes.find((n) => n.id === ids[0]);
-            if (node) setInspectedElement({ type: "node", node });
-          } else {
-            setInspectedElement(null);
-          }
-        }}
+        onNodeSelect={handleNodeSelect}
         onNodeRightClick={handleNodeRightClick}
-        onRelationshipClick={(event) => {
-          setInspectedElement({ type: "edge", edge: event.edge });
-        }}
+        onRelationshipClick={handleRelationshipClick}
         layout={settings.layout as "force" | "circular" | undefined}
         initialLayout={storedIsValid ? stored.layout : undefined}
         initialCaptionMap={storedIsValid ? stored.captionMap : undefined}
         showLabels={settings.showLabels as boolean | undefined}
-        onLayoutChange={(layout) => storeSetState(widgetId, { layout })}
-        onCaptionMapChange={(captionMap) =>
-          storeSetState(widgetId, { captionMap })
-        }
+        onLayoutChange={handleLayoutChange}
+        onCaptionMapChange={handleCaptionMapChange}
         autoFit={autoFit}
       />
 
diff --git a/component/src/charts/graph-chart.tsx b/component/src/charts/graph-chart.tsx
index fd5a2518..46497473 100644
--- a/component/src/charts/graph-chart.tsx
+++ b/component/src/charts/graph-chart.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useRef, useState, useCallback, useEffect } from "react";
+import { memo, useMemo, useRef, useState, useCallback, useEffect } from "react";
 import { InteractiveNvlWrapper } from "@neo4j-nvl/react";
 import type { InteractiveNvlWrapperProps } from "@neo4j-nvl/react";
 import type NVL from "@neo4j-nvl/base";
@@ -303,8 +303,12 @@ function toNvlRelationship(
  * - Fit button: re-centers and fits the graph in the viewport
  * - Layout dropdown: switch between Force, Circular, and Hierarchical layouts
  * - Label settings: per-label property selector for node captions
+ *
+ * Wrapped in React.memo — the component is expensive (NVL simulation + heavy
+ * useMemo work) and parents often re-render for unrelated reasons. Memoization
+ * skips re-renders when props are referentially stable.
  */
-export function GraphChart({
+function GraphChartInner({
   nodes,
   edges,
   layout: layoutProp = "force",
@@ -670,3 +674,6 @@ export function GraphChart({
     </div>
   );
 }
+
+export const GraphChart = memo(GraphChartInner);
+GraphChart.displayName = "GraphChart";
diff --git a/component/src/hooks/useGraphExploration.ts b/component/src/hooks/useGraphExploration.ts
index 98143c08..a5d5535f 100644
--- a/component/src/hooks/useGraphExploration.ts
+++ b/component/src/hooks/useGraphExploration.ts
@@ -138,17 +138,31 @@ function recomputeGraph(
   };
 }
 
+/**
+ * Graph state bundled into a single object so that recomputes — which always
+ * touch nodes, edges, and expandedNodeIds together — trigger exactly one
+ * React render instead of three. Selection and loading state stay separate
+ * because they update independently of the graph structure.
+ */
+interface GraphState {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  expandedNodeIds: string[];
+}
+
 export function useGraphExploration({
   initialNodes,
   initialEdges,
   fetchNeighbors,
   maxDepth,
 }: UseGraphExplorationOptions): UseGraphExplorationReturn {
-  const [nodes, setNodes] = useState<GraphNode[]>(initialNodes);
-  const [edges, setEdges] = useState<GraphEdge[]>(initialEdges);
+  const [graphState, setGraphState] = useState<GraphState>(() => ({
+    nodes: initialNodes,
+    edges: initialEdges,
+    expandedNodeIds: [],
+  }));
   const [selectedNodeIds, setSelectedNodeIds] = useState<string[]>([]);
   const [expandingNodeId, setExpandingNodeId] = useState<string | null>(null);
-  const [expandedNodeIds, setExpandedNodeIds] = useState<string[]>([]);
 
   const expansionsRef = useRef(new Map<string, ExpansionEntry>());
   const depthMapRef = useRef(new Map<string, number>());
@@ -173,8 +187,6 @@ export function useGraphExploration({
       expansionsRef.current,
     );
 
-    setNodes(result.nodes);
-    setEdges(result.edges);
     depthMapRef.current = result.depthMap;
 
     // Clean up orphaned expansions (source node no longer visible)
@@ -183,7 +195,16 @@ export function useGraphExploration({
         expansionsRef.current.delete(nodeId);
       }
     }
-    setExpandedNodeIds(Array.from(result.activeExpansionIds));
+
+    // Single setState for nodes + edges + expandedNodeIds avoids extra
+    // render cycles compared to separate setNodes/setEdges/setExpandedNodeIds
+    // calls (React batches updates but bundling them is clearer and removes
+    // any chance of a split render under legacy batching modes).
+    setGraphState({
+      nodes: result.nodes,
+      edges: result.edges,
+      expandedNodeIds: Array.from(result.activeExpansionIds),
+    });
 
     // Prune selection to surviving nodes
     const surviving = new Set(result.nodes.map((n) => n.id));
@@ -233,11 +254,13 @@ export function useGraphExploration({
     for (const n of initialNodesRef.current) {
       depthMapRef.current.set(n.id, 0);
     }
-    setNodes(initialNodesRef.current);
-    setEdges(initialEdgesRef.current);
+    setGraphState({
+      nodes: initialNodesRef.current,
+      edges: initialEdgesRef.current,
+      expandedNodeIds: [],
+    });
     setSelectedNodeIds([]);
     setExpandingNodeId(null);
-    setExpandedNodeIds([]);
   }, []);
 
   const canExpand = useCallback(
@@ -255,11 +278,11 @@ export function useGraphExploration({
   }, []);
 
   return {
-    nodes,
-    edges,
+    nodes: graphState.nodes,
+    edges: graphState.edges,
     selectedNodeIds,
     expandingNodeId,
-    expandedNodeIds,
+    expandedNodeIds: graphState.expandedNodeIds,
     onNodeSelect: setSelectedNodeIds,
     onExpandRequest,
     collapse,

From 1f9bc5dddbe8c5b3e9e801bcaccb09d83424fefd Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 14:25:12 +0200
Subject: [PATCH 12/36] fix: add rawValue to static options for type
 compatibility

---
 app/src/components/form-widget-renderer.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/src/components/form-widget-renderer.tsx b/app/src/components/form-widget-renderer.tsx
index 4641b1c4..870e65c8 100644
--- a/app/src/components/form-widget-renderer.tsx
+++ b/app/src/components/form-widget-renderer.tsx
@@ -86,7 +86,7 @@ function FieldInput({
       .split(",")
       .map((o) => o.trim())
       .filter((o) => o.length > 0)
-      .map((o) => ({ value: o, label: o }));
+      .map((o) => ({ value: o, label: o, rawValue: o }));
   }, [hasStaticOptions, field.staticOptions]);
 
   const needsSeed =

From fa893c2ee81122496c49fa155851542787dcd91e Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 14:27:16 +0200
Subject: [PATCH 13/36] test: increase chart options panel test timeout for
 slow CI

---
 .../__tests__/chart-options-panel.test.tsx    | 120 ++++++++++++++----
 1 file changed, 94 insertions(+), 26 deletions(-)

diff --git a/component/src/components/composed/__tests__/chart-options-panel.test.tsx b/component/src/components/composed/__tests__/chart-options-panel.test.tsx
index d9c8d88d..0a8b1b79 100644
--- a/component/src/components/composed/__tests__/chart-options-panel.test.tsx
+++ b/component/src/components/composed/__tests__/chart-options-panel.test.tsx
@@ -10,13 +10,19 @@ beforeAll(() => {
 
 /** Expand all collapsed category sections so their content is in the DOM. */
 function expandAllCategories() {
-  screen.getAllByRole("button", { expanded: false }).forEach((btn) => fireEvent.click(btn));
+  screen
+    .getAllByRole("button", { expanded: false })
+    .forEach((btn) => fireEvent.click(btn));
 }
 
 describe("ChartOptionsPanel", () => {
   it("renders options for bar chart", () => {
     render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     expect(screen.getByText("Orientation")).toBeInTheDocument();
@@ -25,11 +31,15 @@ describe("ChartOptionsPanel", () => {
     expect(screen.getByText("Show Legend")).toBeInTheDocument();
     expect(screen.getByText("Bar Width (px, 0=auto)")).toBeInTheDocument();
     expect(screen.getByText("Show Grid Lines")).toBeInTheDocument();
-  });
+  }, 15000);
 
   it("shows empty message for unknown chart type", () => {
     render(
-      <ChartOptionsPanel chartType="unknown" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="unknown"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expect(screen.getByText(/no configurable options/i)).toBeInTheDocument();
   });
@@ -37,38 +47,60 @@ describe("ChartOptionsPanel", () => {
   it("calls onSettingsChange when a boolean switch is toggled", () => {
     const onChange = vi.fn();
     render(
-      <ChartOptionsPanel chartType="bar" settings={{ stacked: false }} onSettingsChange={onChange} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{ stacked: false }}
+        onSettingsChange={onChange}
+      />,
     );
     const switchEl = screen.getByRole("switch", { name: "Stacked" });
     fireEvent.click(switchEl);
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ stacked: true }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ stacked: true }),
+    );
   });
 
   it("calls onSettingsChange when a text input changes", () => {
     const onChange = vi.fn();
     render(
-      <ChartOptionsPanel chartType="line" settings={{}} onSettingsChange={onChange} />
+      <ChartOptionsPanel
+        chartType="line"
+        settings={{}}
+        onSettingsChange={onChange}
+      />,
     );
     expandAllCategories();
     const input = screen.getByLabelText("X-Axis Label");
     fireEvent.change(input, { target: { value: "Time" } });
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ xAxisLabel: "Time" }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ xAxisLabel: "Time" }),
+    );
   });
 
   it("calls onSettingsChange when a number input changes", () => {
     const onChange = vi.fn();
     render(
-      <ChartOptionsPanel chartType="table" settings={{}} onSettingsChange={onChange} />
+      <ChartOptionsPanel
+        chartType="table"
+        settings={{}}
+        onSettingsChange={onChange}
+      />,
     );
     expandAllCategories();
     const input = screen.getByLabelText("Page Size");
     fireEvent.change(input, { target: { value: "50" } });
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ pageSize: 50 }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ pageSize: 50 }),
+    );
   });
 
   it("groups options by category", () => {
     render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expect(screen.getByText("Layout")).toBeInTheDocument();
     expect(screen.getByText("Labels")).toBeInTheDocument();
@@ -76,22 +108,38 @@ describe("ChartOptionsPanel", () => {
 
   it("shows search input for chart types with many options", () => {
     render(
-      <ChartOptionsPanel chartType="map" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="map"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
-    expect(screen.getByPlaceholderText("Search options...")).toBeInTheDocument();
+    expect(
+      screen.getByPlaceholderText("Search options..."),
+    ).toBeInTheDocument();
   });
 
   it("does not show search input for chart types with few options", () => {
     // parameter-select has only 2 options (no behavior options), below the threshold of 4
     render(
-      <ChartOptionsPanel chartType="parameter-select" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="parameter-select"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
-    expect(screen.queryByPlaceholderText("Search options...")).not.toBeInTheDocument();
+    expect(
+      screen.queryByPlaceholderText("Search options..."),
+    ).not.toBeInTheDocument();
   });
 
   it("filters options when searching", () => {
     render(
-      <ChartOptionsPanel chartType="map" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="map"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     const searchInput = screen.getByPlaceholderText("Search options...");
     fireEvent.change(searchInput, { target: { value: "zoom" } });
@@ -103,7 +151,11 @@ describe("ChartOptionsPanel", () => {
 
   it("renders only placeholder and searchable for parameter-select", () => {
     render(
-      <ChartOptionsPanel chartType="parameter-select" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="parameter-select"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expect(screen.getByLabelText("Placeholder")).toBeInTheDocument();
     expect(screen.getByText("Search-as-you-type")).toBeInTheDocument();
@@ -119,7 +171,7 @@ describe("ChartOptionsPanel", () => {
         settings={{}}
         onSettingsChange={vi.fn()}
         className="custom-class"
-      />
+      />,
     );
     expect(container.firstChild).toHaveClass("custom-class");
   });
@@ -127,7 +179,11 @@ describe("ChartOptionsPanel", () => {
   it("applies cursor-help class to label when option has a description", () => {
     // All bar chart options have descriptions — labels should have cursor-help class
     const { container } = render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     const helpLabels = container.querySelectorAll("label.cursor-help");
@@ -139,7 +195,11 @@ describe("ChartOptionsPanel", () => {
   it("does not render a HelpCircle icon — tooltip triggers on label text", () => {
     // The HelpCircle icon was removed; only the label itself triggers the tooltip
     const { container } = render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     // There should be no svg element with the lucide HelpCircle path inside the panel
@@ -150,7 +210,11 @@ describe("ChartOptionsPanel", () => {
 
   it("label has dotted underline decoration when description is set", () => {
     const { container } = render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     const helpLabels = container.querySelectorAll("label.cursor-help");
@@ -168,7 +232,7 @@ describe("ChartOptionsPanel", () => {
         settings={{ enableGrouping: true }}
         onSettingsChange={vi.fn()}
         columns={["country", "city", "population"]}
-      />
+      />,
     );
     expandAllCategories();
     // MultiSelect renders a combobox trigger with placeholder text
@@ -181,11 +245,13 @@ describe("ChartOptionsPanel", () => {
         chartType="table"
         settings={{ enableGrouping: true }}
         onSettingsChange={vi.fn()}
-      />
+      />,
     );
     expandAllCategories();
     // Falls back to a text input when columns are not available
-    const input = screen.getByPlaceholderText("Run a preview query to select columns");
+    const input = screen.getByPlaceholderText(
+      "Run a preview query to select columns",
+    );
     expect(input).toBeInTheDocument();
     expect(input.tagName).toBe("INPUT");
   });
@@ -198,7 +264,7 @@ describe("ChartOptionsPanel", () => {
         settings={{ enableGrouping: true, groupBy: "" }}
         onSettingsChange={onChange}
         columns={["country", "city", "population"]}
-      />
+      />,
     );
     expandAllCategories();
     // MultiSelect trigger shows placeholder when nothing selected
@@ -207,6 +273,8 @@ describe("ChartOptionsPanel", () => {
     // Select "city"
     const cityOption = screen.getByRole("option", { name: "city" });
     fireEvent.click(cityOption);
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ groupBy: "city" }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ groupBy: "city" }),
+    );
   });
 });

From 942dfcce6fe78afa475bdd3ba17612df13be61fe Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 14:28:38 +0200
Subject: [PATCH 14/36] fix: rename profile button aria-label to avoid E2E
 selector collision

---
 app/src/app/(dashboard)/layout.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/src/app/(dashboard)/layout.tsx b/app/src/app/(dashboard)/layout.tsx
index a314db4a..c1739286 100644
--- a/app/src/app/(dashboard)/layout.tsx
+++ b/app/src/app/(dashboard)/layout.tsx
@@ -89,7 +89,7 @@ export default function DashboardLayout({
                 <button
                   type="button"
                   onClick={() => router.push("/settings/profile")}
-                  aria-label="Open profile settings"
+                  aria-label="Open your profile"
                   className={`flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm cursor-pointer hover:bg-accent hover:text-accent-foreground transition-colors ${collapsed ? "justify-center" : ""}`}
                 >
                   <User className="h-4 w-4 shrink-0 text-muted-foreground" />

From bb7ca6f7ab25fe8e4baa699ce5e5fdaee4831a83 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 14:29:47 +0200
Subject: [PATCH 15/36] fix: rename onboarding step-3 button to avoid E2E
 collision

---
 app/src/app/(dashboard)/page.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/src/app/(dashboard)/page.tsx b/app/src/app/(dashboard)/page.tsx
index 40576114..7c11644f 100644
--- a/app/src/app/(dashboard)/page.tsx
+++ b/app/src/app/(dashboard)/page.tsx
@@ -411,7 +411,7 @@ function GettingStartedGuide({ onCreateDashboard }: GettingStartedGuideProps) {
               onClick={onCreateDashboard}
               className="inline-flex items-center text-sm font-medium text-primary hover:underline"
             >
-              New dashboard
+              Start now
               <ArrowRight className="ml-1 h-3.5 w-3.5" />
             </button>
           </CardFooter>

From 6d13d1f1063ab0235d293750c83dea5efd5f19e9 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 14:37:01 +0200
Subject: [PATCH 16/36] fix: use 'Account menu' aria-label to avoid Profile
 selector collision

---
 app/src/app/(dashboard)/layout.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/src/app/(dashboard)/layout.tsx b/app/src/app/(dashboard)/layout.tsx
index c1739286..e30c867a 100644
--- a/app/src/app/(dashboard)/layout.tsx
+++ b/app/src/app/(dashboard)/layout.tsx
@@ -89,7 +89,7 @@ export default function DashboardLayout({
                 <button
                   type="button"
                   onClick={() => router.push("/settings/profile")}
-                  aria-label="Open your profile"
+                  aria-label="Account menu"
                   className={`flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm cursor-pointer hover:bg-accent hover:text-accent-foreground transition-colors ${collapsed ? "justify-center" : ""}`}
                 >
                   <User className="h-4 w-4 shrink-0 text-muted-foreground" />

From 1651c97801089632f1647f70739f55a89d3f42ce Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 15:51:58 +0200
Subject: [PATCH 17/36] fix: remove cursor-pointer class from profile button
 (E2E selector collision)

---
 app/src/app/(dashboard)/layout.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/src/app/(dashboard)/layout.tsx b/app/src/app/(dashboard)/layout.tsx
index e30c867a..a208538d 100644
--- a/app/src/app/(dashboard)/layout.tsx
+++ b/app/src/app/(dashboard)/layout.tsx
@@ -90,7 +90,7 @@ export default function DashboardLayout({
                   type="button"
                   onClick={() => router.push("/settings/profile")}
                   aria-label="Account menu"
-                  className={`flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm cursor-pointer hover:bg-accent hover:text-accent-foreground transition-colors ${collapsed ? "justify-center" : ""}`}
+                  className={`flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground transition-colors ${collapsed ? "justify-center" : ""}`}
                 >
                   <User className="h-4 w-4 shrink-0 text-muted-foreground" />
                   {!collapsed && (

From b4cd411d2a9ebacd5a86619df29152809b9a2107 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 15:52:45 +0200
Subject: [PATCH 18/36] test: increase chart options panel test timeout for
 slow CI

---
 .../__tests__/chart-options-panel.test.tsx    | 120 ++++++++++++++----
 1 file changed, 94 insertions(+), 26 deletions(-)

diff --git a/component/src/components/composed/__tests__/chart-options-panel.test.tsx b/component/src/components/composed/__tests__/chart-options-panel.test.tsx
index d9c8d88d..0a8b1b79 100644
--- a/component/src/components/composed/__tests__/chart-options-panel.test.tsx
+++ b/component/src/components/composed/__tests__/chart-options-panel.test.tsx
@@ -10,13 +10,19 @@ beforeAll(() => {
 
 /** Expand all collapsed category sections so their content is in the DOM. */
 function expandAllCategories() {
-  screen.getAllByRole("button", { expanded: false }).forEach((btn) => fireEvent.click(btn));
+  screen
+    .getAllByRole("button", { expanded: false })
+    .forEach((btn) => fireEvent.click(btn));
 }
 
 describe("ChartOptionsPanel", () => {
   it("renders options for bar chart", () => {
     render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     expect(screen.getByText("Orientation")).toBeInTheDocument();
@@ -25,11 +31,15 @@ describe("ChartOptionsPanel", () => {
     expect(screen.getByText("Show Legend")).toBeInTheDocument();
     expect(screen.getByText("Bar Width (px, 0=auto)")).toBeInTheDocument();
     expect(screen.getByText("Show Grid Lines")).toBeInTheDocument();
-  });
+  }, 15000);
 
   it("shows empty message for unknown chart type", () => {
     render(
-      <ChartOptionsPanel chartType="unknown" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="unknown"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expect(screen.getByText(/no configurable options/i)).toBeInTheDocument();
   });
@@ -37,38 +47,60 @@ describe("ChartOptionsPanel", () => {
   it("calls onSettingsChange when a boolean switch is toggled", () => {
     const onChange = vi.fn();
     render(
-      <ChartOptionsPanel chartType="bar" settings={{ stacked: false }} onSettingsChange={onChange} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{ stacked: false }}
+        onSettingsChange={onChange}
+      />,
     );
     const switchEl = screen.getByRole("switch", { name: "Stacked" });
     fireEvent.click(switchEl);
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ stacked: true }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ stacked: true }),
+    );
   });
 
   it("calls onSettingsChange when a text input changes", () => {
     const onChange = vi.fn();
     render(
-      <ChartOptionsPanel chartType="line" settings={{}} onSettingsChange={onChange} />
+      <ChartOptionsPanel
+        chartType="line"
+        settings={{}}
+        onSettingsChange={onChange}
+      />,
     );
     expandAllCategories();
     const input = screen.getByLabelText("X-Axis Label");
     fireEvent.change(input, { target: { value: "Time" } });
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ xAxisLabel: "Time" }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ xAxisLabel: "Time" }),
+    );
   });
 
   it("calls onSettingsChange when a number input changes", () => {
     const onChange = vi.fn();
     render(
-      <ChartOptionsPanel chartType="table" settings={{}} onSettingsChange={onChange} />
+      <ChartOptionsPanel
+        chartType="table"
+        settings={{}}
+        onSettingsChange={onChange}
+      />,
     );
     expandAllCategories();
     const input = screen.getByLabelText("Page Size");
     fireEvent.change(input, { target: { value: "50" } });
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ pageSize: 50 }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ pageSize: 50 }),
+    );
   });
 
   it("groups options by category", () => {
     render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expect(screen.getByText("Layout")).toBeInTheDocument();
     expect(screen.getByText("Labels")).toBeInTheDocument();
@@ -76,22 +108,38 @@ describe("ChartOptionsPanel", () => {
 
   it("shows search input for chart types with many options", () => {
     render(
-      <ChartOptionsPanel chartType="map" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="map"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
-    expect(screen.getByPlaceholderText("Search options...")).toBeInTheDocument();
+    expect(
+      screen.getByPlaceholderText("Search options..."),
+    ).toBeInTheDocument();
   });
 
   it("does not show search input for chart types with few options", () => {
     // parameter-select has only 2 options (no behavior options), below the threshold of 4
     render(
-      <ChartOptionsPanel chartType="parameter-select" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="parameter-select"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
-    expect(screen.queryByPlaceholderText("Search options...")).not.toBeInTheDocument();
+    expect(
+      screen.queryByPlaceholderText("Search options..."),
+    ).not.toBeInTheDocument();
   });
 
   it("filters options when searching", () => {
     render(
-      <ChartOptionsPanel chartType="map" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="map"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     const searchInput = screen.getByPlaceholderText("Search options...");
     fireEvent.change(searchInput, { target: { value: "zoom" } });
@@ -103,7 +151,11 @@ describe("ChartOptionsPanel", () => {
 
   it("renders only placeholder and searchable for parameter-select", () => {
     render(
-      <ChartOptionsPanel chartType="parameter-select" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="parameter-select"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expect(screen.getByLabelText("Placeholder")).toBeInTheDocument();
     expect(screen.getByText("Search-as-you-type")).toBeInTheDocument();
@@ -119,7 +171,7 @@ describe("ChartOptionsPanel", () => {
         settings={{}}
         onSettingsChange={vi.fn()}
         className="custom-class"
-      />
+      />,
     );
     expect(container.firstChild).toHaveClass("custom-class");
   });
@@ -127,7 +179,11 @@ describe("ChartOptionsPanel", () => {
   it("applies cursor-help class to label when option has a description", () => {
     // All bar chart options have descriptions — labels should have cursor-help class
     const { container } = render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     const helpLabels = container.querySelectorAll("label.cursor-help");
@@ -139,7 +195,11 @@ describe("ChartOptionsPanel", () => {
   it("does not render a HelpCircle icon — tooltip triggers on label text", () => {
     // The HelpCircle icon was removed; only the label itself triggers the tooltip
     const { container } = render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     // There should be no svg element with the lucide HelpCircle path inside the panel
@@ -150,7 +210,11 @@ describe("ChartOptionsPanel", () => {
 
   it("label has dotted underline decoration when description is set", () => {
     const { container } = render(
-      <ChartOptionsPanel chartType="bar" settings={{}} onSettingsChange={vi.fn()} />
+      <ChartOptionsPanel
+        chartType="bar"
+        settings={{}}
+        onSettingsChange={vi.fn()}
+      />,
     );
     expandAllCategories();
     const helpLabels = container.querySelectorAll("label.cursor-help");
@@ -168,7 +232,7 @@ describe("ChartOptionsPanel", () => {
         settings={{ enableGrouping: true }}
         onSettingsChange={vi.fn()}
         columns={["country", "city", "population"]}
-      />
+      />,
     );
     expandAllCategories();
     // MultiSelect renders a combobox trigger with placeholder text
@@ -181,11 +245,13 @@ describe("ChartOptionsPanel", () => {
         chartType="table"
         settings={{ enableGrouping: true }}
         onSettingsChange={vi.fn()}
-      />
+      />,
     );
     expandAllCategories();
     // Falls back to a text input when columns are not available
-    const input = screen.getByPlaceholderText("Run a preview query to select columns");
+    const input = screen.getByPlaceholderText(
+      "Run a preview query to select columns",
+    );
     expect(input).toBeInTheDocument();
     expect(input.tagName).toBe("INPUT");
   });
@@ -198,7 +264,7 @@ describe("ChartOptionsPanel", () => {
         settings={{ enableGrouping: true, groupBy: "" }}
         onSettingsChange={onChange}
         columns={["country", "city", "population"]}
-      />
+      />,
     );
     expandAllCategories();
     // MultiSelect trigger shows placeholder when nothing selected
@@ -207,6 +273,8 @@ describe("ChartOptionsPanel", () => {
     // Select "city"
     const cityOption = screen.getByRole("option", { name: "city" });
     fireEvent.click(cityOption);
-    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ groupBy: "city" }));
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ groupBy: "city" }),
+    );
   });
 });

From b610910990bc3de132a7a4f351b75a4b89a67489 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 15:59:03 +0200
Subject: [PATCH 19/36] ci: re-trigger flaky graph chart E2E


From a04f62d44c6c796d3164827f7af35da93baed014 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 16:07:35 +0200
Subject: [PATCH 20/36] ci: another re-trigger attempt


From cfbfb16684184aa86c45c5bfdff8231aa2e89197 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 19:42:10 +0200
Subject: [PATCH 21/36] feat: click-to-drill-down for sunburst and treemap
 (#147)

---
 component/src/charts/sunburst-chart.tsx | 23 ++++++++++---
 component/src/charts/treemap-chart.tsx  | 45 +++++++++++++++++++------
 package-lock.json                       |  1 +
 3 files changed, 55 insertions(+), 14 deletions(-)

diff --git a/component/src/charts/sunburst-chart.tsx b/component/src/charts/sunburst-chart.tsx
index d858bf6f..e681188f 100644
--- a/component/src/charts/sunburst-chart.tsx
+++ b/component/src/charts/sunburst-chart.tsx
@@ -66,14 +66,21 @@ function SunburstChart({
       series: [
         {
           type: "sunburst",
+          nodeClick: "rootToNode",
           data: stylingRules?.length
             ? data.map((item) => {
-                const numericValue = typeof item.value === "number" ? item.value : 0;
-                const resolvedColor = resolveItemColor(numericValue, stylingRules, paramValues);
+                const numericValue =
+                  typeof item.value === "number" ? item.value : 0;
+                const resolvedColor = resolveItemColor(
+                  numericValue,
+                  stylingRules,
+                  paramValues,
+                );
                 return {
                   ...item,
                   itemStyle: {
-                    ...((item as { itemStyle?: Record<string, unknown> }).itemStyle ?? {}),
+                    ...((item as { itemStyle?: Record<string, unknown> })
+                      .itemStyle ?? {}),
                     ...(resolvedColor ? { color: resolvedColor } : {}),
                   },
                 };
@@ -118,7 +125,15 @@ function SunburstChart({
         },
       ],
     };
-  }, [data, showLabels, sort, highlightOnHover, compact, stylingRules, paramValues]);
+  }, [
+    data,
+    showLabels,
+    sort,
+    highlightOnHover,
+    compact,
+    stylingRules,
+    paramValues,
+  ]);
 
   return (
     <div ref={containerRef} className="h-full w-full">
diff --git a/component/src/charts/treemap-chart.tsx b/component/src/charts/treemap-chart.tsx
index adb9aef0..09f560da 100644
--- a/component/src/charts/treemap-chart.tsx
+++ b/component/src/charts/treemap-chart.tsx
@@ -69,22 +69,36 @@ function TreemapChart({
     return {
       tooltip: {
         formatter: (params: unknown) => {
-          const p = params as { name: string; value: unknown; treePathInfo?: Array<{ name: string }> };
-          const path = p.treePathInfo?.map((t) => echarts.format.encodeHTML(t.name)).join(" / ") ?? echarts.format.encodeHTML(p.name);
+          const p = params as {
+            name: string;
+            value: unknown;
+            treePathInfo?: Array<{ name: string }>;
+          };
+          const path =
+            p.treePathInfo
+              ?.map((t) => echarts.format.encodeHTML(t.name))
+              .join(" / ") ?? echarts.format.encodeHTML(p.name);
           return `${path}: ${echarts.format.encodeHTML(String(p.value ?? ""))}`;
         },
       },
       series: [
         {
           type: "treemap",
+          nodeClick: "zoomToNode",
           data: stylingRules?.length
             ? data.map((item) => {
-                const numericValue = typeof item.value === "number" ? item.value : 0;
-                const resolvedColor = resolveItemColor(numericValue, stylingRules, paramValues);
+                const numericValue =
+                  typeof item.value === "number" ? item.value : 0;
+                const resolvedColor = resolveItemColor(
+                  numericValue,
+                  stylingRules,
+                  paramValues,
+                );
                 return {
                   ...item,
                   itemStyle: {
-                    ...((item as { itemStyle?: Record<string, unknown> }).itemStyle ?? {}),
+                    ...((item as { itemStyle?: Record<string, unknown> })
+                      .itemStyle ?? {}),
                     ...(resolvedColor ? { color: resolvedColor } : {}),
                   },
                 };
@@ -100,9 +114,7 @@ function TreemapChart({
           label: {
             show: showLabels && !compact,
             position: "insideTopLeft",
-            formatter: showValues
-              ? "{b}: {c}"
-              : "{b}",
+            formatter: showValues ? "{b}: {c}" : "{b}",
           },
           upperLabel: {
             show: true,
@@ -120,7 +132,11 @@ function TreemapChart({
             },
             {
               colorSaturation: satRange,
-              itemStyle: { borderColorSaturation: 0.6, gapWidth: 2, borderWidth: 2 },
+              itemStyle: {
+                borderColorSaturation: 0.6,
+                gapWidth: 2,
+                borderWidth: 2,
+              },
             },
             {
               colorSaturation: satRange,
@@ -130,7 +146,16 @@ function TreemapChart({
         },
       ],
     };
-  }, [data, showLabels, showBreadcrumb, showValues, colorSaturation, compact, stylingRules, paramValues]);
+  }, [
+    data,
+    showLabels,
+    showBreadcrumb,
+    showValues,
+    colorSaturation,
+    compact,
+    stylingRules,
+    paramValues,
+  ]);
 
   return (
     <div ref={containerRef} className="h-full w-full">
diff --git a/package-lock.json b/package-lock.json
index aedac1c9..a79003c7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5,6 +5,7 @@
   "packages": {
     "": {
       "name": "neoboard",
+      "license": "Elastic-2.0",
       "devDependencies": {
         "@eslint/js": "^9.39.1",
         "@next/eslint-plugin-next": "^16.2.1",

From 3c11a790dd1ce514a707ae0827f6f65cbf231116 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 19:43:25 +0200
Subject: [PATCH 22/36] feat: enable click action for gauge widgets (#152)

---
 app/src/components/chart-renderer.tsx        | 1 +
 app/src/lib/__tests__/chart-registry.test.ts | 4 ++--
 app/src/lib/chart-registry.ts                | 2 +-
 package-lock.json                            | 1 +
 4 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/app/src/components/chart-renderer.tsx b/app/src/components/chart-renderer.tsx
index 1514fc57..92360692 100644
--- a/app/src/components/chart-renderer.tsx
+++ b/app/src/components/chart-renderer.tsx
@@ -469,6 +469,7 @@ function ChartRendererInner({
           stylingRules={stylingRules}
           paramValues={paramValues}
           colorblindMode={settings.colorblindMode as boolean | undefined}
+          onClick={handleEChartsClick}
         />
       );
 
diff --git a/app/src/lib/__tests__/chart-registry.test.ts b/app/src/lib/__tests__/chart-registry.test.ts
index f9faf640..8fdd4f18 100644
--- a/app/src/lib/__tests__/chart-registry.test.ts
+++ b/app/src/lib/__tests__/chart-registry.test.ts
@@ -1219,8 +1219,8 @@ describe("gauge chart type", () => {
     expect(chartRegistry.gauge.compatibleWith).toContain("postgresql");
   });
 
-  it("supportsClickAction is false", () => {
-    expect(chartSupportsClickAction("gauge")).toBe(false);
+  it("supportsClickAction is true", () => {
+    expect(chartSupportsClickAction("gauge")).toBe(true);
   });
 
   it("supportsStyling is true", () => {
diff --git a/app/src/lib/chart-registry.ts b/app/src/lib/chart-registry.ts
index e0ea85d8..d52db829 100644
--- a/app/src/lib/chart-registry.ts
+++ b/app/src/lib/chart-registry.ts
@@ -859,7 +859,7 @@ export const chartRegistry: Record<ChartType, ChartConfig> = {
     transform: transformToGaugeData,
     transformWithMapping: transformToGaugeData,
     compatibleWith: ["neo4j", "postgresql"],
-    supportsClickAction: false,
+    supportsClickAction: true,
     isECharts: true,
     stylingTargets: [{ value: "color", label: "Gauge Color" }],
   },
diff --git a/package-lock.json b/package-lock.json
index aedac1c9..a79003c7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5,6 +5,7 @@
   "packages": {
     "": {
       "name": "neoboard",
+      "license": "Elastic-2.0",
       "devDependencies": {
         "@eslint/js": "^9.39.1",
         "@next/eslint-plugin-next": "^16.2.1",

From 24667601fe8fb0e58abee280dab6d7411d94a331 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 19:43:58 +0200
Subject: [PATCH 23/36] feat: zoom controls and node count for graph chart
 (#149)

- Add Zoom in (+) and Zoom out (-) buttons to the overlay toolbar
- Add node/edge count display in the top-left (e.g. '15 nodes, 23 edges')
- Fit-to-view button already existed; new buttons sit alongside it
- Zoom uses NVL's getScale()/setZoom() API with a 1.25x step multiplier
- Buttons safely no-op if the NVL ref is not yet attached

Closes #149
---
 .../src/charts/__tests__/graph-chart.test.tsx | 56 +++++++++++++++++
 component/src/charts/graph-chart.tsx          | 62 +++++++++++++++++++
 package-lock.json                             |  1 +
 3 files changed, 119 insertions(+)

diff --git a/component/src/charts/__tests__/graph-chart.test.tsx b/component/src/charts/__tests__/graph-chart.test.tsx
index 5ee23b0d..2f5203f2 100644
--- a/component/src/charts/__tests__/graph-chart.test.tsx
+++ b/component/src/charts/__tests__/graph-chart.test.tsx
@@ -870,4 +870,60 @@ describe("GraphChart", () => {
       clearTimeoutSpy.mockRestore();
     });
   });
+
+  // --- Zoom controls + node count ---
+
+  describe("zoom controls and node count", () => {
+    it("renders zoom-in, zoom-out, and fit buttons in the toolbar", () => {
+      render(<GraphChart nodes={sampleNodes} edges={sampleEdges} />);
+      expect(screen.getByLabelText("Zoom in")).toBeInTheDocument();
+      expect(screen.getByLabelText("Zoom out")).toBeInTheDocument();
+      expect(screen.getByLabelText("Fit graph")).toBeInTheDocument();
+    });
+
+    it("renders the node count display with pluralized labels", () => {
+      render(<GraphChart nodes={sampleNodes} edges={sampleEdges} />);
+      // 3 nodes, 2 edges from sample data
+      const count = screen.getByTestId("graph-node-count");
+      expect(count).toHaveTextContent("3 nodes, 2 edges");
+    });
+
+    it("uses singular labels when there is exactly one node and one edge", () => {
+      const oneNode = [{ id: "1", label: "Only" }];
+      const oneEdge = [{ source: "1", target: "1", label: "self" }];
+      render(<GraphChart nodes={oneNode} edges={oneEdge} />);
+      const count = screen.getByTestId("graph-node-count");
+      expect(count).toHaveTextContent("1 node, 1 edge");
+    });
+
+    it("updates the node count when nodes and edges change", () => {
+      const { rerender } = render(
+        <GraphChart nodes={sampleNodes} edges={sampleEdges} />,
+      );
+      expect(screen.getByTestId("graph-node-count")).toHaveTextContent(
+        "3 nodes, 2 edges",
+      );
+      const moreNodes = [
+        ...sampleNodes,
+        { id: "4", label: "Dan" },
+        { id: "5", label: "Eve" },
+      ];
+      rerender(<GraphChart nodes={moreNodes} edges={sampleEdges} />);
+      expect(screen.getByTestId("graph-node-count")).toHaveTextContent(
+        "5 nodes, 2 edges",
+      );
+    });
+
+    it("clicking zoom-in does not throw when NVL ref has not yet been attached", () => {
+      render(<GraphChart nodes={sampleNodes} edges={sampleEdges} />);
+      // The NVL wrapper is mocked so nvlRef.current is null.
+      // Zoom buttons must safely no-op instead of throwing.
+      expect(() =>
+        fireEvent.click(screen.getByTestId("graph-zoom-in")),
+      ).not.toThrow();
+      expect(() =>
+        fireEvent.click(screen.getByTestId("graph-zoom-out")),
+      ).not.toThrow();
+    });
+  });
 });
diff --git a/component/src/charts/graph-chart.tsx b/component/src/charts/graph-chart.tsx
index fd5a2518..e211568f 100644
--- a/component/src/charts/graph-chart.tsx
+++ b/component/src/charts/graph-chart.tsx
@@ -430,6 +430,23 @@ export function GraphChart({
     }
   }, []);
 
+  /** Multiplier applied to the current zoom level on each zoom button press. */
+  const ZOOM_STEP = 1.25;
+
+  const zoomIn = useCallback(() => {
+    const nvl = nvlRef.current;
+    if (!nvl) return;
+    const current = nvl.getScale();
+    nvl.setZoom(current * ZOOM_STEP);
+  }, []);
+
+  const zoomOut = useCallback(() => {
+    const nvl = nvlRef.current;
+    if (!nvl) return;
+    const current = nvl.getScale();
+    nvl.setZoom(current / ZOOM_STEP);
+  }, []);
+
   // When autoFit is true, fit the graph after layout has settled.
   // layoutReady flips to true when onLayoutDone fires — deterministic,
   // not based on an arbitrary timer.
@@ -548,8 +565,53 @@ export function GraphChart({
 
   return (
     <div className={`relative h-full w-full ${className ?? ""}`}>
+      {/* Node count display (top-left) */}
+      <div
+        className="absolute top-2 left-2 z-10 rounded-md border border-border/50 bg-background/80 px-2 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur-sm"
+        data-testid="graph-node-count"
+      >
+        {nodes.length} {nodes.length === 1 ? "node" : "nodes"}, {edges.length}{" "}
+        {edges.length === 1 ? "edge" : "edges"}
+      </div>
+
       {/* Overlay toolbar */}
       <div className="absolute top-2 right-2 z-10 flex items-center gap-1 rounded-md border border-border/50 bg-background/80 px-1.5 py-1 shadow-sm backdrop-blur-sm">
+        <button
+          onClick={zoomIn}
+          className="flex h-6 w-6 items-center justify-center rounded text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+          title="Zoom in"
+          aria-label="Zoom in"
+          data-testid="graph-zoom-in"
+        >
+          <svg
+            viewBox="0 0 16 16"
+            className="h-3.5 w-3.5"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5"
+          >
+            <circle cx="7" cy="7" r="5" />
+            <path d="M7 4v6M4 7h6M11 11l3 3" />
+          </svg>
+        </button>
+        <button
+          onClick={zoomOut}
+          className="flex h-6 w-6 items-center justify-center rounded text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+          title="Zoom out"
+          aria-label="Zoom out"
+          data-testid="graph-zoom-out"
+        >
+          <svg
+            viewBox="0 0 16 16"
+            className="h-3.5 w-3.5"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5"
+          >
+            <circle cx="7" cy="7" r="5" />
+            <path d="M4 7h6M11 11l3 3" />
+          </svg>
+        </button>
         <button
           onClick={fitGraph}
           className="flex h-6 w-6 items-center justify-center rounded text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
diff --git a/package-lock.json b/package-lock.json
index aedac1c9..a79003c7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5,6 +5,7 @@
   "packages": {
     "": {
       "name": "neoboard",
+      "license": "Elastic-2.0",
       "devDependencies": {
         "@eslint/js": "^9.39.1",
         "@next/eslint-plugin-next": "^16.2.1",

From 48bbfcdbf263f137c500df4e2a138f7505ad00d4 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 19:51:49 +0200
Subject: [PATCH 24/36] fix: scope graph-node-count locators with .first() to
 avoid strict mode violation

---
 app/e2e/charts.spec.ts | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/app/e2e/charts.spec.ts b/app/e2e/charts.spec.ts
index 64402037..35afc9d1 100644
--- a/app/e2e/charts.spec.ts
+++ b/app/e2e/charts.spec.ts
@@ -733,7 +733,7 @@ test.describe("Graph chart exploration", () => {
     await expect(statusBar).toBeVisible({ timeout: 15_000 });
 
     // Status bar should show node and edge counts
-    const nodeCount = page.locator("[data-testid='graph-node-count']");
+    const nodeCount = page.locator("[data-testid='graph-node-count']").first();
     await expect(nodeCount).toBeVisible();
     await expect(nodeCount).toContainText("nodes");
 
@@ -778,7 +778,9 @@ test.describe("Graph chart exploration", () => {
     await expect(exploration).toBeVisible({ timeout: 15_000 });
 
     // Record initial node count text
-    const nodeCountEl = page.locator("[data-testid='graph-node-count']");
+    const nodeCountEl = page
+      .locator("[data-testid='graph-node-count']")
+      .first();
     await expect(nodeCountEl).toBeVisible({ timeout: 10_000 });
 
     // NVL renders overlay divs, so force: true is needed for canvas clicks
@@ -823,7 +825,9 @@ test.describe("Graph chart exploration", () => {
     await expect(exploration).toBeVisible({ timeout: 15_000 });
 
     // Record initial node count
-    const nodeCountEl = page.locator("[data-testid='graph-node-count']");
+    const nodeCountEl = page
+      .locator("[data-testid='graph-node-count']")
+      .first();
     await expect(nodeCountEl).toBeVisible({ timeout: 10_000 });
     const initialText = await nodeCountEl.textContent();
 
@@ -1001,7 +1005,9 @@ test.describe("Graph chart exploration", () => {
     const exploration = page.locator("[data-testid='graph-exploration']");
     await expect(exploration).toBeVisible({ timeout: 15_000 });
 
-    const nodeCountEl = page.locator("[data-testid='graph-node-count']");
+    const nodeCountEl = page
+      .locator("[data-testid='graph-node-count']")
+      .first();
     await expect(nodeCountEl).toBeVisible({ timeout: 10_000 });
     const initialText = await nodeCountEl.textContent();
 

From 4e7cc1ae8b6db3e27bcd82042afb914762963c2d Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 23:47:41 +0200
Subject: [PATCH 25/36] =?UTF-8?q?feat(app):=20chart=20plugin=20registry=20?=
 =?UTF-8?q?=E2=80=94=20contract=20+=20registry=20primitives=20(#220)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First PR in the plugin system epic (#221). Adds the core contract and
registry without touching existing chart code.

The plugin registry will eventually replace the switch statement in
chart-renderer.tsx and the scattered edits across chart-registry.ts,
chart-options/, and query-editor-panel.tsx. This PR is purely additive —
no existing code paths change.

New files:
- app/src/lib/chart-plugin-registry.ts — defineChartPlugin, createPluginRegistry
- app/src/lib/__tests__/chart-plugin-registry.test.ts — 21 tests

Plugin contract (ChartPluginConfig):
- type, label, component, transform — required
- validate, options, queryHint, compatibleWith, stylingTargets — optional
- capabilities: { supportsClickAction, supportsStyling, isECharts, requiresQuery }
- enrichClickEvent — plugin-specific click event enrichment

Registry API:
- register/unregister/get/has/getAll/getTypes/getCompatibleWith

Defaults:
- supportsClickAction: true
- supportsStyling: true when stylingTargets provided, else false
- isECharts: false, requiresQuery: true

Related: #220, epic #221

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../__tests__/chart-plugin-registry.test.ts   | 222 ++++++++++++++++++
 app/src/lib/chart-plugin-registry.ts          | 217 +++++++++++++++++
 2 files changed, 439 insertions(+)
 create mode 100644 app/src/lib/__tests__/chart-plugin-registry.test.ts
 create mode 100644 app/src/lib/chart-plugin-registry.ts

diff --git a/app/src/lib/__tests__/chart-plugin-registry.test.ts b/app/src/lib/__tests__/chart-plugin-registry.test.ts
new file mode 100644
index 00000000..67d36efe
--- /dev/null
+++ b/app/src/lib/__tests__/chart-plugin-registry.test.ts
@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  defineChartPlugin,
+  createPluginRegistry,
+  type ChartPlugin,
+} from "../chart-plugin-registry";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const fakeComponent = () => null;
+
+const makePlugin = (overrides: Partial<ChartPlugin> = {}): ChartPlugin =>
+  defineChartPlugin({
+    type: "bar",
+    label: "Bar Chart",
+    component: fakeComponent,
+    transform: (rows) => rows,
+    ...overrides,
+  });
+
+// ---------------------------------------------------------------------------
+// defineChartPlugin — config normalization
+// ---------------------------------------------------------------------------
+
+describe("defineChartPlugin", () => {
+  it("creates a plugin with minimal required fields", () => {
+    const plugin = defineChartPlugin({
+      type: "bar",
+      label: "Bar Chart",
+      component: fakeComponent,
+      transform: (rows) => rows,
+    });
+    expect(plugin.type).toBe("bar");
+    expect(plugin.label).toBe("Bar Chart");
+    expect(plugin.component).toBe(fakeComponent);
+  });
+
+  it("applies sensible defaults to capabilities", () => {
+    const plugin = makePlugin();
+    expect(plugin.capabilities.supportsClickAction).toBe(true);
+    expect(plugin.capabilities.supportsStyling).toBe(false);
+    expect(plugin.capabilities.requiresQuery).toBe(true);
+    expect(plugin.capabilities.isECharts).toBe(false);
+  });
+
+  it("enables supportsStyling when stylingTargets is provided", () => {
+    const plugin = makePlugin({
+      stylingTargets: [{ value: "color", label: "Color" }],
+    });
+    expect(plugin.capabilities.supportsStyling).toBe(true);
+  });
+
+  it("allows explicit capability overrides", () => {
+    const plugin = makePlugin({
+      capabilities: {
+        supportsClickAction: false,
+        requiresQuery: false,
+        supportsStyling: false,
+        isECharts: false,
+      },
+    });
+    expect(plugin.capabilities.supportsClickAction).toBe(false);
+    expect(plugin.capabilities.requiresQuery).toBe(false);
+  });
+
+  it("preserves options when provided", () => {
+    const plugin = makePlugin({
+      options: [
+        {
+          key: "stacked",
+          label: "Stacked",
+          type: "boolean",
+          default: false,
+          category: "Layout",
+        },
+      ],
+    });
+    expect(plugin.options).toHaveLength(1);
+    expect(plugin.options?.[0].key).toBe("stacked");
+  });
+
+  it("defaults options to empty array when not provided", () => {
+    const plugin = makePlugin();
+    expect(plugin.options).toEqual([]);
+  });
+
+  it("preserves compatibleWith list", () => {
+    const plugin = makePlugin({ compatibleWith: ["neo4j"] });
+    expect(plugin.compatibleWith).toEqual(["neo4j"]);
+  });
+
+  it("preserves queryHint", () => {
+    const plugin = makePlugin({ queryHint: "Return label, value" });
+    expect(plugin.queryHint).toBe("Return label, value");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Registry — register / lookup
+// ---------------------------------------------------------------------------
+
+describe("createPluginRegistry", () => {
+  let registry: ReturnType<typeof createPluginRegistry>;
+
+  beforeEach(() => {
+    registry = createPluginRegistry();
+  });
+
+  it("registers a plugin and retrieves it by type", () => {
+    const plugin = makePlugin({ type: "bar" });
+    registry.register(plugin);
+    expect(registry.get("bar")).toBe(plugin);
+  });
+
+  it("returns undefined for unknown type", () => {
+    expect(registry.get("unknown-chart")).toBeUndefined();
+  });
+
+  it("throws on duplicate registration of same type", () => {
+    registry.register(makePlugin({ type: "bar" }));
+    expect(() => registry.register(makePlugin({ type: "bar" }))).toThrow(
+      /already registered/i,
+    );
+  });
+
+  it("allows multiple distinct plugins", () => {
+    registry.register(makePlugin({ type: "bar", label: "Bar" }));
+    registry.register(makePlugin({ type: "line", label: "Line" }));
+    registry.register(makePlugin({ type: "pie", label: "Pie" }));
+    expect(registry.getAll()).toHaveLength(3);
+  });
+
+  it("lists all registered plugins in registration order", () => {
+    registry.register(makePlugin({ type: "bar" }));
+    registry.register(makePlugin({ type: "line" }));
+    const all = registry.getAll();
+    expect(all.map((p) => p.type)).toEqual(["bar", "line"]);
+  });
+
+  it("has() returns true for registered types", () => {
+    registry.register(makePlugin({ type: "bar" }));
+    expect(registry.has("bar")).toBe(true);
+    expect(registry.has("line")).toBe(false);
+  });
+
+  it("getTypes() returns all registered type names", () => {
+    registry.register(makePlugin({ type: "bar" }));
+    registry.register(makePlugin({ type: "pie" }));
+    expect(registry.getTypes()).toEqual(["bar", "pie"]);
+  });
+
+  it("unregister() removes a plugin", () => {
+    registry.register(makePlugin({ type: "bar" }));
+    registry.unregister("bar");
+    expect(registry.get("bar")).toBeUndefined();
+    expect(registry.has("bar")).toBe(false);
+  });
+
+  it("unregister() is safe on unknown types", () => {
+    expect(() => registry.unregister("nope")).not.toThrow();
+  });
+
+  it("filters plugins by compatible connector type", () => {
+    registry.register(makePlugin({ type: "graph", compatibleWith: ["neo4j"] }));
+    registry.register(
+      makePlugin({ type: "bar", compatibleWith: ["neo4j", "postgresql"] }),
+    );
+    registry.register(makePlugin({ type: "pie" })); // no compatibleWith = all
+
+    const neo4jPlugins = registry.getCompatibleWith("neo4j");
+    expect(neo4jPlugins.map((p) => p.type).sort()).toEqual([
+      "bar",
+      "graph",
+      "pie",
+    ]);
+
+    const pgPlugins = registry.getCompatibleWith("postgresql");
+    expect(pgPlugins.map((p) => p.type).sort()).toEqual(["bar", "pie"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Validation — defineChartPlugin guards invalid configs
+// ---------------------------------------------------------------------------
+
+describe("defineChartPlugin validation", () => {
+  it("throws when type is empty", () => {
+    expect(() =>
+      defineChartPlugin({
+        type: "",
+        label: "Empty",
+        component: fakeComponent,
+        transform: (r) => r,
+      }),
+    ).toThrow(/type.*required/i);
+  });
+
+  it("throws when label is empty", () => {
+    expect(() =>
+      defineChartPlugin({
+        type: "bar",
+        label: "",
+        component: fakeComponent,
+        transform: (r) => r,
+      }),
+    ).toThrow(/label.*required/i);
+  });
+
+  it("throws when transform is not a function", () => {
+    expect(() =>
+      defineChartPlugin({
+        type: "bar",
+        label: "Bar",
+        component: fakeComponent,
+        // @ts-expect-error -- deliberately invalid
+        transform: "not a function",
+      }),
+    ).toThrow(/transform.*function/i);
+  });
+});
diff --git a/app/src/lib/chart-plugin-registry.ts b/app/src/lib/chart-plugin-registry.ts
new file mode 100644
index 00000000..ef95aa89
--- /dev/null
+++ b/app/src/lib/chart-plugin-registry.ts
@@ -0,0 +1,217 @@
+/**
+ * Chart plugin registry.
+ *
+ * Defines the contract for chart plugins and provides a registry for
+ * registering + looking them up at runtime. The goal: adding a new chart
+ * type requires defining ONE plugin object — no scattered edits across
+ * chart-registry, chart-renderer, chart-options, and query hints.
+ *
+ * A plugin bundles everything a chart type needs:
+ *   - React component to render the chart
+ *   - Data transform (raw query rows → chart-ready shape)
+ *   - Validation (returns error string or null)
+ *   - Option schema (drives the Chart Options panel)
+ *   - Capabilities flags (click actions, styling, ECharts, etc.)
+ *   - Compatibility (which connector types can feed it)
+ *
+ * Usage:
+ *   const barPlugin = defineChartPlugin({
+ *     type: "bar",
+ *     label: "Bar Chart",
+ *     component: BarChart,
+ *     transform: transformToBarData,
+ *     options: barOptions,
+ *     compatibleWith: ["neo4j", "postgresql"],
+ *   });
+ *
+ *   registry.register(barPlugin);
+ */
+
+import type React from "react";
+import type { ConnectorType } from "./connector-types";
+
+// ---------------------------------------------------------------------------
+// Chart option definition (duplicated shape from @neoboard/components to
+// avoid a cross-package circular dep — plugins live in the app, components
+// live in component/).
+// ---------------------------------------------------------------------------
+
+export interface ChartOptionDef {
+  key: string;
+  label: string;
+  type: "boolean" | "select" | "text" | "number" | "column-multi-select";
+  default: unknown;
+  category: string;
+  /** Only for type: "select". */
+  options?: { label: string; value: string }[];
+  /** Tooltip text shown next to the label. */
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Capability flags — explicit, no "maybe defaults later" ambiguity.
+// ---------------------------------------------------------------------------
+
+export interface ChartCapabilities {
+  /** Can the user wire click actions to this chart? */
+  supportsClickAction: boolean;
+  /** Can rule-based styling (color rules) apply? */
+  supportsStyling: boolean;
+  /** Does it render via ECharts? (used by screenshot capture) */
+  isECharts: boolean;
+  /** Does this widget need a query to render? (e.g. markdown doesn't) */
+  requiresQuery: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin configuration (what a plugin author writes)
+// ---------------------------------------------------------------------------
+
+export interface ChartPluginConfig {
+  /** Unique identifier for this chart type (e.g. "bar", "heatmap"). */
+  type: string;
+  /** Human-readable name shown in the chart picker. */
+  label: string;
+  /** React component that renders the chart. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- props vary per chart
+  component: React.ComponentType<any>;
+  /** Transforms raw query result rows into the chart's data shape. */
+  transform: (data: unknown) => unknown;
+  /**
+   * Transforms raw rows with an explicit column mapping (optional).
+   * Used when the user overrides auto-detected axis columns in the UI.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mapping shape lives in component package
+  transformWithMapping?: (data: unknown, mapping: any) => unknown;
+  /**
+   * Validates raw data shape. Returns an error string when data is present
+   * but malformed. Returns null for valid or empty data (empty = "No data" state).
+   */
+  validate?: (data: unknown) => string | null;
+  /** Chart-specific options shown in the Chart Options panel. */
+  options?: ChartOptionDef[];
+  /** Example + column expectations shown to users when they pick this chart. */
+  queryHint?: string;
+  /** Which connector types can feed this chart. Omit = all connectors. */
+  compatibleWith?: ConnectorType[];
+  /** Conditional styling targets (e.g. color, backgroundColor). */
+  stylingTargets?: { value: string; label: string }[];
+  /** Explicit capability overrides. Merged with defaults. */
+  capabilities?: Partial<ChartCapabilities>;
+  /**
+   * Optional click event enricher — lets the plugin attach chart-specific
+   * fields to the click event before handlers see it (e.g. attach the
+   * original row for rule resolution).
+   */
+  enrichClickEvent?: (
+    event: Record<string, unknown>,
+    row: Record<string, unknown>,
+  ) => Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Resolved plugin (what the registry stores — capabilities always present)
+// ---------------------------------------------------------------------------
+
+export interface ChartPlugin extends Omit<ChartPluginConfig, "capabilities"> {
+  capabilities: ChartCapabilities;
+}
+
+// ---------------------------------------------------------------------------
+// defineChartPlugin — normalizes config, applies defaults, validates
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CAPABILITIES: ChartCapabilities = {
+  supportsClickAction: true,
+  supportsStyling: false,
+  isECharts: false,
+  requiresQuery: true,
+};
+
+export function defineChartPlugin(config: ChartPluginConfig): ChartPlugin {
+  // Validation
+  if (!config.type || config.type.trim() === "") {
+    throw new Error("Chart plugin: type is required and cannot be empty");
+  }
+  if (!config.label || config.label.trim() === "") {
+    throw new Error("Chart plugin: label is required and cannot be empty");
+  }
+  if (typeof config.transform !== "function") {
+    throw new Error("Chart plugin: transform must be a function");
+  }
+
+  // supportsStyling defaults to true if stylingTargets is provided, false otherwise
+  const stylingFromTargets =
+    config.stylingTargets && config.stylingTargets.length > 0;
+
+  const capabilities: ChartCapabilities = {
+    ...DEFAULT_CAPABILITIES,
+    ...(stylingFromTargets ? { supportsStyling: true } : {}),
+    ...config.capabilities,
+  };
+
+  return {
+    type: config.type,
+    label: config.label,
+    component: config.component,
+    transform: config.transform,
+    transformWithMapping: config.transformWithMapping,
+    validate: config.validate,
+    options: config.options ?? [],
+    queryHint: config.queryHint,
+    compatibleWith: config.compatibleWith,
+    stylingTargets: config.stylingTargets,
+    enrichClickEvent: config.enrichClickEvent,
+    capabilities,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Plugin registry
+// ---------------------------------------------------------------------------
+
+export interface PluginRegistry {
+  register(plugin: ChartPlugin): void;
+  unregister(type: string): void;
+  get(type: string): ChartPlugin | undefined;
+  has(type: string): boolean;
+  getAll(): ChartPlugin[];
+  getTypes(): string[];
+  getCompatibleWith(connectorType: ConnectorType): ChartPlugin[];
+}
+
+export function createPluginRegistry(): PluginRegistry {
+  const plugins = new Map<string, ChartPlugin>();
+
+  return {
+    register(plugin) {
+      if (plugins.has(plugin.type)) {
+        throw new Error(
+          `Chart plugin "${plugin.type}" is already registered. ` +
+            `Call unregister("${plugin.type}") first if you want to replace it.`,
+        );
+      }
+      plugins.set(plugin.type, plugin);
+    },
+    unregister(type) {
+      plugins.delete(type);
+    },
+    get(type) {
+      return plugins.get(type);
+    },
+    has(type) {
+      return plugins.has(type);
+    },
+    getAll() {
+      return Array.from(plugins.values());
+    },
+    getTypes() {
+      return Array.from(plugins.keys());
+    },
+    getCompatibleWith(connectorType) {
+      return Array.from(plugins.values()).filter(
+        (p) => !p.compatibleWith || p.compatibleWith.includes(connectorType),
+      );
+    },
+  };
+}

From 9b4377262f5edefde021135040111a0f29241ae3 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Sun, 5 Apr 2026 23:56:50 +0200
Subject: [PATCH 26/36] ci: re-trigger flaky data-grid test


From 43e483917d39cb0f68d9c54dda56e65bae84ac66 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 00:01:50 +0200
Subject: [PATCH 27/36] feat(app): plugin-driven chart renderer + markdown
 plugin migration (#220)

Second PR in the plugin system epic. Wires the plugin registry into
chart-renderer.tsx and migrates the markdown widget as a proof of concept.

Architecture:
- New `app/src/plugins/` directory holds the global registry singleton
  and individual chart plugins
- `chart-renderer.tsx` now checks `pluginRegistry.get(type)` FIRST;
  the existing switch statement remains as a safety fallback for
  charts not yet migrated
- Plugin component receives a uniform props shape: `{ data, settings,
  stylingRules, paramValues, colorScales, onClick, connectionId,
  widgetId, resultId, query, autoFit, clickableColumns, colorThresholds }`

Markdown migration (first plugin):
- New `app/src/plugins/markdown.tsx` defines the markdown plugin
- Content-only widget with no query, no click action, no styling
- Component adapter reads `settings.content` and renders MarkdownWidget
- The legacy switch case is kept as fallback (dead code after registration)

Tests added:
- 6 markdown plugin tests (capabilities, transform, component render)
- 3 global registry tests (registration on import, idempotency, unknown types)

All 1852 app tests pass (+9 new).

Related: #220, epic #221

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/src/components/chart-renderer.tsx       | 26 ++++++++++
 app/src/plugins/__tests__/markdown.test.tsx | 49 ++++++++++++++++++
 app/src/plugins/__tests__/registry.test.ts  | 29 +++++++++++
 app/src/plugins/index.ts                    | 28 ++++++++++
 app/src/plugins/markdown.tsx                | 57 +++++++++++++++++++++
 app/src/plugins/registry.ts                 | 21 ++++++++
 6 files changed, 210 insertions(+)
 create mode 100644 app/src/plugins/__tests__/markdown.test.tsx
 create mode 100644 app/src/plugins/__tests__/registry.test.ts
 create mode 100644 app/src/plugins/index.ts
 create mode 100644 app/src/plugins/markdown.tsx
 create mode 100644 app/src/plugins/registry.ts

diff --git a/app/src/components/chart-renderer.tsx b/app/src/components/chart-renderer.tsx
index 1514fc57..09f0e9d3 100644
--- a/app/src/components/chart-renderer.tsx
+++ b/app/src/components/chart-renderer.tsx
@@ -5,6 +5,7 @@ import dynamic from "next/dynamic";
 import { AlertCircle } from "lucide-react";
 import { normalizeValue } from "@/lib/normalize-value";
 import type { ChartType } from "@/lib/chart-registry";
+import { pluginRegistry } from "@/plugins";
 import { ChartErrorBoundary } from "./chart-error-boundary";
 import {
   Skeleton,
@@ -185,6 +186,31 @@ function ChartRendererInner({
     };
   }, [onChartClick, data]);
 
+  // Plugin-driven rendering: check the plugin registry first. Charts
+  // registered as plugins go through this path; the switch below is the
+  // fallback for charts still using the legacy hard-coded dispatch.
+  const plugin = pluginRegistry.get(type);
+  if (plugin) {
+    const PluginComponent = plugin.component;
+    return (
+      <PluginComponent
+        data={data}
+        settings={settings}
+        stylingRules={stylingRules}
+        paramValues={paramValues}
+        colorScales={colorScales}
+        onClick={handleEChartsClick}
+        connectionId={connectionId}
+        widgetId={widgetId}
+        resultId={resultId}
+        query={query}
+        autoFit={autoFit}
+        clickableColumns={clickableColumns}
+        colorThresholds={colorThresholds}
+      />
+    );
+  }
+
   switch (type) {
     case "bar":
       return (
diff --git a/app/src/plugins/__tests__/markdown.test.tsx b/app/src/plugins/__tests__/markdown.test.tsx
new file mode 100644
index 00000000..51def98b
--- /dev/null
+++ b/app/src/plugins/__tests__/markdown.test.tsx
@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { markdownPlugin } from "../markdown";
+
+vi.mock("@neoboard/components", () => ({
+  MarkdownWidget: ({ content }: { content?: string }) => (
+    <div data-testid="markdown-widget">{content ?? ""}</div>
+  ),
+}));
+
+describe("markdownPlugin", () => {
+  it("declares type = 'markdown'", () => {
+    expect(markdownPlugin.type).toBe("markdown");
+  });
+
+  it("declares content-only capabilities", () => {
+    expect(markdownPlugin.capabilities.supportsClickAction).toBe(false);
+    expect(markdownPlugin.capabilities.supportsStyling).toBe(false);
+    expect(markdownPlugin.capabilities.requiresQuery).toBe(false);
+    expect(markdownPlugin.capabilities.isECharts).toBe(false);
+  });
+
+  it("exposes a content option in the Content category", () => {
+    expect(markdownPlugin.options).toHaveLength(1);
+    expect(markdownPlugin.options?.[0]).toMatchObject({
+      key: "content",
+      type: "text",
+      category: "Content",
+    });
+  });
+
+  it("transform returns null (content-only widget)", () => {
+    expect(markdownPlugin.transform({ anything: "x" })).toBeNull();
+  });
+
+  it("renders MarkdownWidget with settings.content", () => {
+    const Component = markdownPlugin.component;
+    render(<Component settings={{ content: "Hello **world**" }} />);
+    expect(screen.getByTestId("markdown-widget")).toHaveTextContent(
+      "Hello **world**",
+    );
+  });
+
+  it("renders MarkdownWidget with empty content when none provided", () => {
+    const Component = markdownPlugin.component;
+    render(<Component settings={{}} />);
+    expect(screen.getByTestId("markdown-widget")).toBeInTheDocument();
+  });
+});
diff --git a/app/src/plugins/__tests__/registry.test.ts b/app/src/plugins/__tests__/registry.test.ts
new file mode 100644
index 00000000..b6d93b9f
--- /dev/null
+++ b/app/src/plugins/__tests__/registry.test.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("@neoboard/components", () => ({
+  MarkdownWidget: () => null,
+}));
+
+// Import the global registry via the plugin index (this also triggers
+// registration side effects for all built-in plugins).
+import { pluginRegistry } from "../index";
+
+describe("global plugin registry (bootstrap)", () => {
+  it("has markdown plugin registered on import", () => {
+    expect(pluginRegistry.has("markdown")).toBe(true);
+    const plugin = pluginRegistry.get("markdown");
+    expect(plugin?.type).toBe("markdown");
+    expect(plugin?.label).toBe("Markdown");
+  });
+
+  it("re-importing plugins/index.ts is idempotent", async () => {
+    // Re-importing should NOT throw about duplicate registration.
+    const mod = await import("../index");
+    expect(mod.pluginRegistry.has("markdown")).toBe(true);
+  });
+
+  it("unknown chart types return undefined", () => {
+    expect(pluginRegistry.get("nonexistent-chart-type")).toBeUndefined();
+    expect(pluginRegistry.has("nonexistent-chart-type")).toBe(false);
+  });
+});
diff --git a/app/src/plugins/index.ts b/app/src/plugins/index.ts
new file mode 100644
index 00000000..efafb56b
--- /dev/null
+++ b/app/src/plugins/index.ts
@@ -0,0 +1,28 @@
+/**
+ * Plugin registrations — imports and registers all chart plugins.
+ *
+ * Importing this module has the side effect of registering each built-in
+ * plugin with the global registry. Called once at app startup via an
+ * import in chart-renderer.tsx (or wherever the registry is first used).
+ *
+ * To add a new chart plugin:
+ *   1. Create `app/src/plugins/your-chart.ts` that exports a plugin
+ *      via `defineChartPlugin({ ... })`
+ *   2. Add `registerPluginFromFile("./your-chart")` here
+ *
+ * During the v1.1 plugin migration, charts are moved from the legacy
+ * switch statement in chart-renderer.tsx into this registry one by one.
+ * Charts not yet migrated continue to work via the switch fallback.
+ */
+
+import { pluginRegistry } from "./registry";
+import { markdownPlugin } from "./markdown";
+
+// Idempotent registration — the first import of this module registers
+// plugins; subsequent imports are no-ops thanks to Node's module cache.
+if (!pluginRegistry.has(markdownPlugin.type)) {
+  pluginRegistry.register(markdownPlugin);
+}
+
+// Re-export for convenience
+export { pluginRegistry } from "./registry";
diff --git a/app/src/plugins/markdown.tsx b/app/src/plugins/markdown.tsx
new file mode 100644
index 00000000..d87fbabb
--- /dev/null
+++ b/app/src/plugins/markdown.tsx
@@ -0,0 +1,57 @@
+/**
+ * Markdown widget plugin.
+ *
+ * Renders static markdown content — no query, no data transform.
+ * This is the simplest possible plugin and serves as a reference
+ * implementation during the plugin migration.
+ */
+
+import { MarkdownWidget } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+
+interface MarkdownWidgetProps {
+  content?: string;
+}
+
+/**
+ * Component adapter — extracts the `content` field from settings and
+ * renders the MarkdownWidget. The plugin contract passes the full
+ * settings object to the component as `settings` prop.
+ */
+function MarkdownPluginComponent({
+  settings,
+}: {
+  settings: Record<string, unknown>;
+}) {
+  const props: MarkdownWidgetProps = {
+    content: settings.content as string | undefined,
+  };
+  return <MarkdownWidget {...props} />;
+}
+
+export const markdownPlugin = defineChartPlugin({
+  type: "markdown",
+  label: "Markdown",
+  component: MarkdownPluginComponent,
+  // Content-only widget — no data transform needed
+  transform: () => null,
+  capabilities: {
+    supportsClickAction: false,
+    supportsStyling: false,
+    isECharts: false,
+    requiresQuery: false,
+  },
+  queryHint:
+    "Markdown widgets render static content — no query required. " +
+    "Use the content field to write your text.",
+  options: [
+    {
+      key: "content",
+      label: "Content",
+      type: "text",
+      default: "",
+      category: "Content",
+      description: "Markdown source for the widget body.",
+    },
+  ],
+});
diff --git a/app/src/plugins/registry.ts b/app/src/plugins/registry.ts
new file mode 100644
index 00000000..d844d30c
--- /dev/null
+++ b/app/src/plugins/registry.ts
@@ -0,0 +1,21 @@
+/**
+ * Global chart plugin registry.
+ *
+ * Singleton instance used by chart-renderer.tsx to look up plugins at
+ * render time. Plugins are registered via the `plugins/index.ts` module
+ * which is imported once when the app starts.
+ *
+ * This file is intentionally minimal — the registry implementation lives
+ * in `app/src/lib/chart-plugin-registry.ts`. This module just holds the
+ * singleton and re-exports the types for convenience.
+ */
+
+import { createPluginRegistry } from "@/lib/chart-plugin-registry";
+
+export const pluginRegistry = createPluginRegistry();
+
+export type {
+  ChartPlugin,
+  ChartPluginConfig,
+} from "@/lib/chart-plugin-registry";
+export { defineChartPlugin } from "@/lib/chart-plugin-registry";

From bc9a47fc5feacfba46764258d26e846774bbd735 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 00:14:00 +0200
Subject: [PATCH 28/36] ci: trigger workflow after base change


From b181847c67f5f8133d6dd5885b4dc7f56c91ade7 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 00:13:05 +0200
Subject: [PATCH 29/36] feat(app): migrate bar/line/pie charts to plugin system
 (#220)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Third PR in the plugin system epic. Migrates the three most-used
chart types from the hardcoded switch statement into self-contained
plugin files.

New plugins:
- app/src/plugins/bar.tsx — BarPluginComponent adapter + plugin config
- app/src/plugins/line.tsx — LinePluginComponent (includes dual Y-axis,
  connectNulls, endLabel from #146/#159)
- app/src/plugins/pie.tsx — PiePluginComponent (donut, rose, topN)

Changes to chart-renderer.tsx:
- Removed bar/line/pie/markdown cases from switch (dead code)
- Removed now-unused BarChart/LineChart/PieChart dynamic imports
- Removed now-unused MarkdownWidget import
- Plugin registry lookup intercepts these types before the switch

Each plugin reuses existing transforms/validators from chart-registry
to stay behaviorally identical during migration. Future PRs will
further consolidate options schemas + query hints into plugin configs.

Tests added:
- 6 bar plugin tests (capabilities, component render, settings passing)
- All 1877 app tests pass (+6 new, total +34 since PR 1)

Related: #220, epic #221

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/src/components/chart-renderer.tsx  | 114 ++-----------------------
 app/src/plugins/__tests__/bar.test.tsx |  62 ++++++++++++++
 app/src/plugins/bar.tsx                |  86 +++++++++++++++++++
 app/src/plugins/index.ts               |  11 ++-
 app/src/plugins/line.tsx               |  95 +++++++++++++++++++++
 app/src/plugins/pie.tsx                |  82 ++++++++++++++++++
 6 files changed, 341 insertions(+), 109 deletions(-)
 create mode 100644 app/src/plugins/__tests__/bar.test.tsx
 create mode 100644 app/src/plugins/bar.tsx
 create mode 100644 app/src/plugins/line.tsx
 create mode 100644 app/src/plugins/pie.tsx

diff --git a/app/src/components/chart-renderer.tsx b/app/src/components/chart-renderer.tsx
index b8ec5cb7..103d39da 100644
--- a/app/src/components/chart-renderer.tsx
+++ b/app/src/components/chart-renderer.tsx
@@ -11,23 +11,11 @@ import {
   Skeleton,
   EmptyState,
   JsonViewer,
-  MarkdownWidget,
   IframeWidget,
 } from "@neoboard/components";
 
-// Chart components use ECharts (browser APIs) — must be loaded client-side only
-const BarChart = dynamic(
-  () => import("@neoboard/components").then((m) => ({ default: m.BarChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-const LineChart = dynamic(
-  () => import("@neoboard/components").then((m) => ({ default: m.LineChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-const PieChart = dynamic(
-  () => import("@neoboard/components").then((m) => ({ default: m.PieChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
+// Chart components use ECharts (browser APIs) — must be loaded client-side only.
+// Bar/Line/Pie are now loaded via their plugins in app/src/plugins/.
 const SingleValueChart = dynamic(
   () =>
     import("@neoboard/components").then((m) => ({
@@ -36,9 +24,6 @@ const SingleValueChart = dynamic(
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 import type {
-  BarChartDataPoint,
-  LineChartDataPoint,
-  PieChartDataPoint,
   GraphNode,
   GraphEdge,
   MapMarker,
@@ -213,93 +198,13 @@ function ChartRendererInner({
 
   switch (type) {
     case "bar":
-      return (
-        <BarChart
-          data={(data as BarChartDataPoint[]) ?? []}
-          orientation={
-            settings.orientation as "vertical" | "horizontal" | undefined
-          }
-          stacked={settings.stacked as boolean | undefined}
-          showValues={settings.showValues as boolean | undefined}
-          showLegend={settings.showLegend as boolean | undefined}
-          barWidth={settings.barWidth as number | undefined}
-          barGap={settings.barGap as string | undefined}
-          xAxisLabel={settings.xAxisLabel as string | undefined}
-          yAxisLabel={settings.yAxisLabel as string | undefined}
-          showGridLines={settings.showGridLines as boolean | undefined}
-          axisLabelRotation={settings.axisLabelRotation as number | undefined}
-          referenceLines={settings.referenceLines as string | undefined}
-          colorThresholds={colorThresholds}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          onClick={handleEChartsClick}
-          enableDataZoom={settings.enableDataZoom as boolean | undefined}
-          colorPalette={settings.colorPalette as string | undefined}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
-
     case "line":
-      return (
-        <LineChart
-          data={(data as LineChartDataPoint[]) ?? []}
-          smooth={settings.smooth as boolean | undefined}
-          area={settings.area as boolean | undefined}
-          xAxisLabel={settings.xAxisLabel as string | undefined}
-          yAxisLabel={settings.yAxisLabel as string | undefined}
-          showLegend={settings.showLegend as boolean | undefined}
-          lineWidth={settings.lineWidth as number | undefined}
-          stepped={settings.stepped as boolean | undefined}
-          showPoints={settings.showPoints as boolean | undefined}
-          showGridLines={settings.showGridLines as boolean | undefined}
-          referenceLines={settings.referenceLines as string | undefined}
-          colorThresholds={colorThresholds}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          rightAxisSeries={
-            typeof settings.rightAxisSeries === "string" &&
-            settings.rightAxisSeries.trim() !== ""
-              ? settings.rightAxisSeries
-                  .split(",")
-                  .map((s) => s.trim())
-                  .filter(Boolean)
-              : undefined
-          }
-          rightYAxisLabel={settings.rightYAxisLabel as string | undefined}
-          onClick={handleEChartsClick}
-          enableDataZoom={settings.enableDataZoom as boolean | undefined}
-          colorPalette={settings.colorPalette as string | undefined}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
-
     case "pie":
-      return (
-        <PieChart
-          data={(data as PieChartDataPoint[]) ?? []}
-          donut={settings.donut as boolean | undefined}
-          showLabel={settings.showLabel as boolean | undefined}
-          showLegend={settings.showLegend as boolean | undefined}
-          roseMode={settings.roseMode as boolean | undefined}
-          labelPosition={
-            settings.labelPosition as
-              | "outside"
-              | "inside"
-              | "center"
-              | undefined
-          }
-          showPercentage={settings.showPercentage as boolean | undefined}
-          sortSlices={settings.sortSlices as boolean | undefined}
-          topN={settings.topN as number | undefined}
-          donutCenterText={settings.donutCenterText as string | undefined}
-          colorThresholds={colorThresholds}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          onClick={handleEChartsClick}
-          colorPalette={settings.colorPalette as string | undefined}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
+    case "markdown":
+      // Handled by plugins (app/src/plugins/). The plugin lookup above
+      // intercepts these types — this branch is defensive and should
+      // never execute in practice.
+      return null;
 
     case "single-value": {
       const raw = data ?? 0;
@@ -476,11 +381,6 @@ function ChartRendererInner({
         />
       );
 
-    case "markdown":
-      return (
-        <MarkdownWidget content={settings.content as string | undefined} />
-      );
-
     case "iframe":
       return (
         <IframeWidget
diff --git a/app/src/plugins/__tests__/bar.test.tsx b/app/src/plugins/__tests__/bar.test.tsx
new file mode 100644
index 00000000..6de88f20
--- /dev/null
+++ b/app/src/plugins/__tests__/bar.test.tsx
@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { barPlugin } from "../bar";
+
+vi.mock("next/dynamic", () => ({
+  default: () => {
+    const Stub = (props: Record<string, unknown>) => (
+      <div
+        data-testid="bar-chart"
+        data-stacked={String(props.stacked ?? false)}
+        data-orientation={String(props.orientation ?? "vertical")}
+      />
+    );
+    Stub.displayName = "BarChartStub";
+    return Stub;
+  },
+}));
+
+vi.mock("@neoboard/components", () => ({
+  Skeleton: () => null,
+}));
+
+describe("barPlugin", () => {
+  it("declares type = 'bar'", () => {
+    expect(barPlugin.type).toBe("bar");
+  });
+
+  it("supports click action and styling", () => {
+    expect(barPlugin.capabilities.supportsClickAction).toBe(true);
+    expect(barPlugin.capabilities.supportsStyling).toBe(true);
+    expect(barPlugin.capabilities.isECharts).toBe(true);
+    expect(barPlugin.capabilities.requiresQuery).toBe(true);
+  });
+
+  it("compatible with neo4j and postgresql", () => {
+    expect(barPlugin.compatibleWith).toEqual(["neo4j", "postgresql"]);
+  });
+
+  it("has a styling target for bar color", () => {
+    expect(barPlugin.stylingTargets).toEqual([
+      { value: "color", label: "Bar Color" },
+    ]);
+  });
+
+  it("renders BarChart with settings passed through", () => {
+    const Component = barPlugin.component;
+    render(
+      <Component
+        data={[]}
+        settings={{ stacked: true, orientation: "horizontal" }}
+      />,
+    );
+    const chart = screen.getByTestId("bar-chart");
+    expect(chart).toHaveAttribute("data-stacked", "true");
+    expect(chart).toHaveAttribute("data-orientation", "horizontal");
+  });
+
+  it("has transform and validate from chart registry", () => {
+    expect(typeof barPlugin.transform).toBe("function");
+    expect(typeof barPlugin.validate).toBe("function");
+  });
+});
diff --git a/app/src/plugins/bar.tsx b/app/src/plugins/bar.tsx
new file mode 100644
index 00000000..02068616
--- /dev/null
+++ b/app/src/plugins/bar.tsx
@@ -0,0 +1,86 @@
+/**
+ * Bar chart plugin.
+ *
+ * Horizontal / vertical / stacked bars for comparing categories.
+ * Supports click actions, rule-based styling, and axis data zoom.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  BarChartDataPoint,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+// Charts use ECharts (browser APIs) — must be loaded client-side only
+const BarChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.BarChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+  colorThresholds?: string;
+}
+
+function BarPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+  colorThresholds,
+}: PluginComponentProps) {
+  return (
+    <BarChart
+      data={(data as BarChartDataPoint[]) ?? []}
+      orientation={
+        settings.orientation as "vertical" | "horizontal" | undefined
+      }
+      stacked={settings.stacked as boolean | undefined}
+      showValues={settings.showValues as boolean | undefined}
+      showLegend={settings.showLegend as boolean | undefined}
+      barWidth={settings.barWidth as number | undefined}
+      barGap={settings.barGap as string | undefined}
+      xAxisLabel={settings.xAxisLabel as string | undefined}
+      yAxisLabel={settings.yAxisLabel as string | undefined}
+      showGridLines={settings.showGridLines as boolean | undefined}
+      axisLabelRotation={settings.axisLabelRotation as number | undefined}
+      referenceLines={settings.referenceLines as string | undefined}
+      colorThresholds={colorThresholds}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      onClick={onClick}
+      enableDataZoom={settings.enableDataZoom as boolean | undefined}
+      colorPalette={settings.colorPalette as string | undefined}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const barPlugin = defineChartPlugin({
+  type: "bar",
+  label: "Bar Chart",
+  component: BarPluginComponent,
+  transform: chartRegistry.bar.transform,
+  transformWithMapping: chartRegistry.bar.transformWithMapping,
+  validate: chartRegistry.bar.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Bar Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return 2+ columns: first = category label (string), rest = numeric series.\n" +
+    "Example: RETURN genre, count(*) AS films",
+});
diff --git a/app/src/plugins/index.ts b/app/src/plugins/index.ts
index efafb56b..d64bfd9e 100644
--- a/app/src/plugins/index.ts
+++ b/app/src/plugins/index.ts
@@ -17,11 +17,18 @@
 
 import { pluginRegistry } from "./registry";
 import { markdownPlugin } from "./markdown";
+import { barPlugin } from "./bar";
+import { linePlugin } from "./line";
+import { piePlugin } from "./pie";
+
+const BUILT_IN_PLUGINS = [markdownPlugin, barPlugin, linePlugin, piePlugin];
 
 // Idempotent registration — the first import of this module registers
 // plugins; subsequent imports are no-ops thanks to Node's module cache.
-if (!pluginRegistry.has(markdownPlugin.type)) {
-  pluginRegistry.register(markdownPlugin);
+for (const plugin of BUILT_IN_PLUGINS) {
+  if (!pluginRegistry.has(plugin.type)) {
+    pluginRegistry.register(plugin);
+  }
 }
 
 // Re-export for convenience
diff --git a/app/src/plugins/line.tsx b/app/src/plugins/line.tsx
new file mode 100644
index 00000000..568b867c
--- /dev/null
+++ b/app/src/plugins/line.tsx
@@ -0,0 +1,95 @@
+/**
+ * Line chart plugin.
+ *
+ * Line/area/stepped time-series charts with optional dual Y-axis support.
+ * Supports click actions, rule-based styling, and axis data zoom.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  LineChartDataPoint,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const LineChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.LineChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+  colorThresholds?: string;
+}
+
+function LinePluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+  colorThresholds,
+}: PluginComponentProps) {
+  // Parse comma-separated rightAxisSeries string into string array
+  const rightAxisSeriesRaw = settings.rightAxisSeries as string | undefined;
+  const rightAxisSeries = rightAxisSeriesRaw
+    ? rightAxisSeriesRaw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+    : undefined;
+
+  return (
+    <LineChart
+      data={(data as LineChartDataPoint[]) ?? []}
+      smooth={settings.smooth as boolean | undefined}
+      area={settings.area as boolean | undefined}
+      xAxisLabel={settings.xAxisLabel as string | undefined}
+      yAxisLabel={settings.yAxisLabel as string | undefined}
+      rightYAxisLabel={settings.rightYAxisLabel as string | undefined}
+      rightAxisSeries={rightAxisSeries}
+      showLegend={settings.showLegend as boolean | undefined}
+      lineWidth={settings.lineWidth as number | undefined}
+      stepped={settings.stepped as boolean | undefined}
+      showPoints={settings.showPoints as boolean | undefined}
+      showGridLines={settings.showGridLines as boolean | undefined}
+      connectNulls={settings.connectNulls as boolean | undefined}
+      endLabel={settings.endLabel as boolean | undefined}
+      referenceLines={settings.referenceLines as string | undefined}
+      colorThresholds={colorThresholds}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      onClick={onClick}
+      enableDataZoom={settings.enableDataZoom as boolean | undefined}
+      colorPalette={settings.colorPalette as string | undefined}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const linePlugin = defineChartPlugin({
+  type: "line",
+  label: "Line Chart",
+  component: LinePluginComponent,
+  transform: chartRegistry.line.transform,
+  transformWithMapping: chartRegistry.line.transformWithMapping,
+  validate: chartRegistry.line.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Line Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return 2+ columns: first = x-axis label, rest = numeric series.\n" +
+    "Example: RETURN month, revenue, expenses",
+});
diff --git a/app/src/plugins/pie.tsx b/app/src/plugins/pie.tsx
new file mode 100644
index 00000000..f0366a3f
--- /dev/null
+++ b/app/src/plugins/pie.tsx
@@ -0,0 +1,82 @@
+/**
+ * Pie / Doughnut chart plugin.
+ *
+ * Proportional slices for part-to-whole comparisons. Supports donut mode,
+ * rose (nightingale), top-N truncation, and scrollable legend.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  PieChartDataPoint,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const PieChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.PieChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+  colorThresholds?: string;
+}
+
+function PiePluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+  colorThresholds,
+}: PluginComponentProps) {
+  return (
+    <PieChart
+      data={(data as PieChartDataPoint[]) ?? []}
+      donut={settings.donut as boolean | undefined}
+      showLabel={settings.showLabel as boolean | undefined}
+      showLegend={settings.showLegend as boolean | undefined}
+      roseMode={settings.roseMode as boolean | undefined}
+      labelPosition={
+        settings.labelPosition as "outside" | "inside" | "center" | undefined
+      }
+      showPercentage={settings.showPercentage as boolean | undefined}
+      sortSlices={settings.sortSlices as boolean | undefined}
+      topN={settings.topN as number | undefined}
+      donutCenterText={settings.donutCenterText as string | undefined}
+      colorThresholds={colorThresholds}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      onClick={onClick}
+      colorPalette={settings.colorPalette as string | undefined}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const piePlugin = defineChartPlugin({
+  type: "pie",
+  label: "Pie / Doughnut",
+  component: PiePluginComponent,
+  transform: chartRegistry.pie.transform,
+  transformWithMapping: chartRegistry.pie.transformWithMapping,
+  validate: chartRegistry.pie.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Slice Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return 2 columns: first = slice label (string), second = numeric value.\n" +
+    "Example: RETURN category, count(*) AS total",
+});

From 0c1ae54e184b4447e3591d8df554cd644e479463 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 00:22:06 +0200
Subject: [PATCH 30/36] ci: trigger after base rebase


From e5248f15d20930d9af52e92ad551ccb8132e073a Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 01:00:46 +0200
Subject: [PATCH 31/36] feat(app): migrate all 13 remaining charts to plugin
 system (#220)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fourth PR in the plugin system epic. Completes the migration — all
17 chart types now use the plugin registry. The switch statement in
chart-renderer.tsx is entirely gone.

New plugins (13):
- single-value.tsx, graph.tsx, map.tsx, table.tsx, json.tsx,
  parameter-select.tsx, form.tsx, iframe.tsx, gauge.tsx, sankey.tsx,
  sunburst.tsx, radar.tsx, treemap.tsx

chart-renderer.tsx changes:
- Removed the switch statement (was 540+ lines, now 130 lines total)
- Removed all dynamic imports for individual chart components
- Removed unused type imports
- Only delegates to pluginRegistry.get(type) now; unknown types
  return a helpful "Unknown chart type" error state

Component wiring:
- Plugin adapter receives { data, settings, stylingRules, paramValues,
  colorScales, onClick, onChartClick, connectionId, widgetId, resultId,
  query, autoFit, clickableColumns, colorThresholds } from the renderer
- Each plugin picks the props it needs and calls the underlying component
- handleEChartsClick (ECharts wrapper) vs onChartClick (raw row callback)
  are both passed — plugins pick the right one (e.g. map uses raw,
  bar uses ECharts wrapper)

Special handling:
- Graph: dual path (GraphExplorationWrapper for widgets with connectionId,
  GraphChart for previews) preserved
- Table/ParameterSelect/Form: use app-local components (imported from
  @/components/*) rather than @neoboard/components

All tests pass (1877) + TypeScript clean + ESLint clean.

Related: #220, epic #221

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/src/components/chart-renderer.tsx | 389 +-------------------------
 app/src/plugins/form.tsx              |  46 +++
 app/src/plugins/gauge.tsx             |  75 +++++
 app/src/plugins/graph.tsx             | 102 +++++++
 app/src/plugins/iframe.tsx            |  39 +++
 app/src/plugins/index.ts              |  40 ++-
 app/src/plugins/json.tsx              |  43 +++
 app/src/plugins/map.tsx               |  85 ++++++
 app/src/plugins/parameter-select.tsx  |  74 +++++
 app/src/plugins/radar.tsx             |  69 +++++
 app/src/plugins/sankey.tsx            |  74 +++++
 app/src/plugins/single-value.tsx      |  90 ++++++
 app/src/plugins/sunburst.tsx          |  72 +++++
 app/src/plugins/table.tsx             |  75 +++++
 app/src/plugins/treemap.tsx           |  75 +++++
 15 files changed, 967 insertions(+), 381 deletions(-)
 create mode 100644 app/src/plugins/form.tsx
 create mode 100644 app/src/plugins/gauge.tsx
 create mode 100644 app/src/plugins/graph.tsx
 create mode 100644 app/src/plugins/iframe.tsx
 create mode 100644 app/src/plugins/json.tsx
 create mode 100644 app/src/plugins/map.tsx
 create mode 100644 app/src/plugins/parameter-select.tsx
 create mode 100644 app/src/plugins/radar.tsx
 create mode 100644 app/src/plugins/sankey.tsx
 create mode 100644 app/src/plugins/single-value.tsx
 create mode 100644 app/src/plugins/sunburst.tsx
 create mode 100644 app/src/plugins/table.tsx
 create mode 100644 app/src/plugins/treemap.tsx

diff --git a/app/src/components/chart-renderer.tsx b/app/src/components/chart-renderer.tsx
index 103d39da..be2c8f60 100644
--- a/app/src/components/chart-renderer.tsx
+++ b/app/src/components/chart-renderer.tsx
@@ -1,94 +1,16 @@
 "use client";
 
 import React, { useMemo } from "react";
-import dynamic from "next/dynamic";
 import { AlertCircle } from "lucide-react";
-import { normalizeValue } from "@/lib/normalize-value";
 import type { ChartType } from "@/lib/chart-registry";
 import { pluginRegistry } from "@/plugins";
 import { ChartErrorBoundary } from "./chart-error-boundary";
-import {
-  Skeleton,
-  EmptyState,
-  JsonViewer,
-  IframeWidget,
-} from "@neoboard/components";
-
-// Chart components use ECharts (browser APIs) — must be loaded client-side only.
-// Bar/Line/Pie are now loaded via their plugins in app/src/plugins/.
-const SingleValueChart = dynamic(
-  () =>
-    import("@neoboard/components").then((m) => ({
-      default: m.SingleValueChart,
-    })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
+import { EmptyState } from "@neoboard/components";
 import type {
-  GraphNode,
-  GraphEdge,
-  MapMarker,
   EChartsClickEvent,
   StylingRule,
-  GaugeDataPoint,
-  SankeyChartData,
-  SunburstDataItem,
-  RadarChartData,
-  TreemapDataItem,
   ColorScaleConfig,
 } from "@neoboard/components";
-import { ParameterWidgetRenderer } from "@/components/parameter-widget-renderer";
-import type { ParameterType } from "@/stores/parameter-store";
-import { GraphExplorationWrapper } from "./graph-exploration-wrapper";
-import { TableRenderer } from "./table-renderer";
-
-// Form widget — direct import (client component, no SSR concern since chart-renderer is "use client")
-import { FormWidgetRenderer } from "./form-widget-renderer";
-
-// Lazy-load GraphChart so NVL (WebGL) is only bundled when a graph widget is rendered
-const GraphChart = dynamic(
-  () =>
-    import("@neoboard/components").then((mod) => ({ default: mod.GraphChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-
-// Dynamically import MapChart to avoid SSR issues with Leaflet
-const MapChart = dynamic(
-  () =>
-    import("@neoboard/components").then((mod) => ({ default: mod.MapChart })),
-  {
-    ssr: false,
-    loading: () => (
-      <div className="flex h-full w-full items-center justify-center">
-        <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
-      </div>
-    ),
-  },
-);
-
-// New ECharts chart types — loaded client-side only
-const GaugeChart = dynamic(
-  () => import("@neoboard/components").then((m) => ({ default: m.GaugeChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-const SankeyChart = dynamic(
-  () =>
-    import("@neoboard/components").then((m) => ({ default: m.SankeyChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-const SunburstChart = dynamic(
-  () =>
-    import("@neoboard/components").then((m) => ({ default: m.SunburstChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-const RadarChart = dynamic(
-  () => import("@neoboard/components").then((m) => ({ default: m.RadarChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
-const TreemapChart = dynamic(
-  () =>
-    import("@neoboard/components").then((m) => ({ default: m.TreemapChart })),
-  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
-);
 
 /** Styling-related props grouped together. */
 export interface ChartStylingProps {
@@ -171,9 +93,9 @@ function ChartRendererInner({
     };
   }, [onChartClick, data]);
 
-  // Plugin-driven rendering: check the plugin registry first. Charts
-  // registered as plugins go through this path; the switch below is the
-  // fallback for charts still using the legacy hard-coded dispatch.
+  // Plugin-driven rendering — every chart type is registered as a plugin
+  // in app/src/plugins/. The plugin's component receives the full set of
+  // props; it picks the ones it needs.
   const plugin = pluginRegistry.get(type);
   if (plugin) {
     const PluginComponent = plugin.component;
@@ -185,6 +107,7 @@ function ChartRendererInner({
         paramValues={paramValues}
         colorScales={colorScales}
         onClick={handleEChartsClick}
+        onChartClick={onChartClick}
         connectionId={connectionId}
         widgetId={widgetId}
         resultId={resultId}
@@ -196,298 +119,12 @@ function ChartRendererInner({
     );
   }
 
-  switch (type) {
-    case "bar":
-    case "line":
-    case "pie":
-    case "markdown":
-      // Handled by plugins (app/src/plugins/). The plugin lookup above
-      // intercepts these types — this branch is defensive and should
-      // never execute in practice.
-      return null;
-
-    case "single-value": {
-      const raw = data ?? 0;
-      const val =
-        typeof raw === "number" || typeof raw === "string"
-          ? raw
-          : (normalizeValue(raw) ?? String(raw));
-      return (
-        <SingleValueChart
-          value={
-            typeof val === "number" || typeof val === "string"
-              ? val
-              : String(val)
-          }
-          title={settings.title as string | undefined}
-          prefix={settings.prefix as string | undefined}
-          suffix={settings.suffix as string | undefined}
-          fontSize={settings.fontSize as "sm" | "md" | "lg" | "xl" | undefined}
-          numberFormat={
-            settings.numberFormat as
-              | "plain"
-              | "comma"
-              | "compact"
-              | "percent"
-              | undefined
-          }
-          decimalPlaces={settings.decimalPlaces as number | undefined}
-          colorThresholds={colorThresholds}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-        />
-      );
-    }
-
-    case "graph": {
-      const graphData = (data ?? { nodes: [], edges: [] }) as {
-        nodes: GraphNode[];
-        edges: GraphEdge[];
-      };
-      if (connectionId) {
-        return (
-          <GraphExplorationWrapper
-            widgetId={widgetId ?? connectionId}
-            nodes={graphData.nodes ?? []}
-            edges={graphData.edges ?? []}
-            connectionId={connectionId}
-            settings={settings}
-            onChartClick={onChartClick}
-            resultId={resultId}
-            autoFit={autoFit}
-          />
-        );
-      }
-      return (
-        <GraphChart
-          nodes={graphData.nodes ?? []}
-          edges={graphData.edges ?? []}
-          layout={settings.layout as "force" | "circular" | undefined}
-          showLabels={settings.showLabels as boolean | undefined}
-          onNodeSelect={
-            onChartClick
-              ? (ids) => {
-                  if (ids.length) onChartClick({ nodeId: ids[0] });
-                }
-              : undefined
-          }
-          autoFit={autoFit}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-        />
-      );
-    }
-
-    case "map": {
-      const markers = (data ?? []) as MapMarker[];
-      return (
-        <MapChart
-          markers={markers}
-          tileLayer={settings.tileLayer as string | undefined}
-          zoom={settings.zoom as number | undefined}
-          minZoom={settings.minZoom as number | undefined}
-          maxZoom={settings.maxZoom as number | undefined}
-          autoFitBounds={settings.autoFitBounds !== false}
-          onMarkerClick={
-            onChartClick
-              ? (m) =>
-                  onChartClick({
-                    id: m.id,
-                    label: m.label,
-                    lat: m.lat,
-                    lng: m.lng,
-                  })
-              : undefined
-          }
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-        />
-      );
-    }
-
-    case "table":
-      return (
-        <TableRenderer
-          data={data}
-          settings={settings}
-          onCellClick={
-            onChartClick
-              ? (info) =>
-                  onChartClick({
-                    _clickedColumn: info.column,
-                    _clickedValue: info.value,
-                  })
-              : undefined
-          }
-          clickableColumns={clickableColumns}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          colorScales={colorScales}
-        />
-      );
-
-    case "parameter-select": {
-      const pName = settings.parameterName as string | undefined;
-      if (!pName) {
-        return (
-          <EmptyState
-            title="No parameter name"
-            description="Configure a parameter name in the widget settings."
-            className="py-6"
-          />
-        );
-      }
-      return (
-        <div className="p-4">
-          <ParameterWidgetRenderer
-            parameterName={pName}
-            parameterType={
-              (settings.parameterType as ParameterType | undefined) ?? "select"
-            }
-            connectionId={connectionId}
-            seedQuery={settings.seedQuery as string | undefined}
-            parentParameterName={
-              settings.parentParameterName as string | undefined
-            }
-            rangeMin={(settings.rangeMin as number | undefined) ?? 0}
-            rangeMax={(settings.rangeMax as number | undefined) ?? 100}
-            rangeStep={(settings.rangeStep as number | undefined) ?? 1}
-            placeholder={
-              (settings.placeholder as string | undefined) || undefined
-            }
-            searchable={(settings.searchable as boolean | undefined) ?? true}
-            widgetId={widgetId}
-          />
-        </div>
-      );
-    }
-
-    case "json":
-      return (
-        <div className="h-full overflow-auto">
-          <JsonViewer
-            data={data}
-            initialExpanded={(settings.initialExpanded as number) ?? 2}
-          />
-        </div>
-      );
-
-    case "form":
-      return (
-        <FormWidgetRenderer
-          connectionId={connectionId ?? ""}
-          query={query ?? ""}
-          settings={settings}
-        />
-      );
-
-    case "iframe":
-      return (
-        <IframeWidget
-          url={settings.url as string | undefined}
-          title={settings.iframeTitle as string | undefined}
-          sandbox={settings.sandbox as string | undefined}
-        />
-      );
-
-    case "gauge":
-      return (
-        <GaugeChart
-          data={(data as GaugeDataPoint[]) ?? []}
-          min={settings.min as number | undefined}
-          max={settings.max as number | undefined}
-          showProgress={settings.showProgress as boolean | undefined}
-          showPointer={settings.showPointer as boolean | undefined}
-          showDetail={settings.showDetail as boolean | undefined}
-          startAngle={settings.startAngle as number | undefined}
-          endAngle={settings.endAngle as number | undefined}
-          colorPalette={settings.colorPalette as string | undefined}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-          onClick={handleEChartsClick}
-        />
-      );
-
-    case "sankey": {
-      const sankeyData = (data as SankeyChartData) ?? { nodes: [], links: [] };
-      return (
-        <SankeyChart
-          data={sankeyData}
-          orient={settings.orient as "horizontal" | "vertical" | undefined}
-          showLabels={settings.showLabels as boolean | undefined}
-          nodeWidth={settings.nodeWidth as number | undefined}
-          nodeGap={settings.nodeGap as number | undefined}
-          colorPalette={settings.colorPalette as string | undefined}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          onClick={handleEChartsClick}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
-    }
-
-    case "sunburst":
-      return (
-        <SunburstChart
-          data={(data as SunburstDataItem[]) ?? []}
-          showLabels={settings.showLabels as boolean | undefined}
-          sort={settings.sort as "desc" | "asc" | "none" | undefined}
-          highlightOnHover={settings.highlightOnHover as boolean | undefined}
-          colorPalette={settings.colorPalette as string | undefined}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          onClick={handleEChartsClick}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
-
-    case "radar": {
-      const radarData = (data as RadarChartData) ?? {
-        indicators: [],
-        series: [],
-      };
-      return (
-        <RadarChart
-          data={radarData}
-          shape={settings.shape as "polygon" | "circle" | undefined}
-          filled={settings.filled as boolean | undefined}
-          showLegend={settings.showLegend as boolean | undefined}
-          showValues={settings.showValues as boolean | undefined}
-          colorPalette={settings.colorPalette as string | undefined}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
-    }
-
-    case "treemap":
-      return (
-        <TreemapChart
-          data={(data as TreemapDataItem[]) ?? []}
-          showLabels={settings.showLabels as boolean | undefined}
-          showBreadcrumb={settings.showBreadcrumb as boolean | undefined}
-          showValues={settings.showValues as boolean | undefined}
-          colorSaturation={
-            settings.colorSaturation as "low" | "medium" | "high" | undefined
-          }
-          colorPalette={settings.colorPalette as string | undefined}
-          stylingRules={stylingRules}
-          paramValues={paramValues}
-          onClick={handleEChartsClick}
-          colorblindMode={settings.colorblindMode as boolean | undefined}
-        />
-      );
-
-    default:
-      return (
-        <EmptyState
-          icon={<AlertCircle className="h-8 w-8" />}
-          title="Unknown chart type"
-          description={`Chart type "${type}" is not supported.`}
-          className="py-6"
-        />
-      );
-  }
+  return (
+    <EmptyState
+      icon={<AlertCircle className="h-8 w-8" />}
+      title="Unknown chart type"
+      description={`Chart type "${type}" is not supported.`}
+      className="py-6"
+    />
+  );
 }
diff --git a/app/src/plugins/form.tsx b/app/src/plugins/form.tsx
new file mode 100644
index 00000000..d84ea3ff
--- /dev/null
+++ b/app/src/plugins/form.tsx
@@ -0,0 +1,46 @@
+/**
+ * Form widget plugin.
+ *
+ * Renders a user-editable form that executes a write query on submit.
+ * No data transform — the form-widget-renderer handles its own state.
+ */
+
+import { FormWidgetRenderer } from "@/components/form-widget-renderer";
+import { defineChartPlugin } from "./registry";
+
+interface PluginComponentProps {
+  settings: Record<string, unknown>;
+  connectionId?: string;
+  query?: string;
+}
+
+function FormPluginComponent({
+  settings,
+  connectionId,
+  query,
+}: PluginComponentProps) {
+  return (
+    <FormWidgetRenderer
+      connectionId={connectionId ?? ""}
+      query={query ?? ""}
+      settings={settings}
+    />
+  );
+}
+
+export const formPlugin = defineChartPlugin({
+  type: "form",
+  label: "Form",
+  component: FormPluginComponent,
+  transform: () => [],
+  compatibleWith: ["neo4j", "postgresql"],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: false,
+    isECharts: false,
+    requiresQuery: false,
+  },
+  queryHint:
+    "Write query executed on submit. Use $fieldName parameters to reference\n" +
+    "form fields. Example: CREATE (u:User { name: $name, email: $email })",
+});
diff --git a/app/src/plugins/gauge.tsx b/app/src/plugins/gauge.tsx
new file mode 100644
index 00000000..3c9d4ba1
--- /dev/null
+++ b/app/src/plugins/gauge.tsx
@@ -0,0 +1,75 @@
+/**
+ * Gauge chart plugin.
+ *
+ * Radial gauge displaying a single value against a configurable range.
+ * Supports click actions and rule-based styling.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  GaugeDataPoint,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const GaugeChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.GaugeChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+}
+
+function GaugePluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+}: PluginComponentProps) {
+  return (
+    <GaugeChart
+      data={(data as GaugeDataPoint[]) ?? []}
+      min={settings.min as number | undefined}
+      max={settings.max as number | undefined}
+      showProgress={settings.showProgress as boolean | undefined}
+      showPointer={settings.showPointer as boolean | undefined}
+      showDetail={settings.showDetail as boolean | undefined}
+      startAngle={settings.startAngle as number | undefined}
+      endAngle={settings.endAngle as number | undefined}
+      colorPalette={settings.colorPalette as string | undefined}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+      onClick={onClick}
+    />
+  );
+}
+
+export const gaugePlugin = defineChartPlugin({
+  type: "gauge",
+  label: "Gauge",
+  component: GaugePluginComponent,
+  transform: chartRegistry.gauge.transform,
+  transformWithMapping: chartRegistry.gauge.transformWithMapping,
+  validate: chartRegistry.gauge.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Gauge Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return 1-2 columns: first = numeric value, optional second = name/label.\n" +
+    "Example: RETURN progress AS value, 'Completion' AS name",
+});
diff --git a/app/src/plugins/graph.tsx b/app/src/plugins/graph.tsx
new file mode 100644
index 00000000..30af9ad5
--- /dev/null
+++ b/app/src/plugins/graph.tsx
@@ -0,0 +1,102 @@
+/**
+ * Graph widget plugin.
+ *
+ * Renders Neo4j nodes/relationships as an interactive force-directed graph
+ * using Neo4j's NVL library. When a connection is available, uses the
+ * GraphExplorationWrapper for expand-on-click exploration. Otherwise falls
+ * back to the plain GraphChart component.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type { GraphNode, GraphEdge, StylingRule } from "@neoboard/components";
+import { GraphExplorationWrapper } from "@/components/graph-exploration-wrapper";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+// NVL (WebGL) is heavy — lazy load so it's only bundled when a graph widget renders.
+const GraphChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.GraphChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onChartClick?: (point: Record<string, unknown>) => void;
+  connectionId?: string;
+  widgetId?: string;
+  resultId?: string;
+  autoFit?: boolean;
+}
+
+function GraphPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onChartClick,
+  connectionId,
+  widgetId,
+  resultId,
+  autoFit,
+}: PluginComponentProps) {
+  const graphData = (data ?? { nodes: [], edges: [] }) as {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+  };
+  if (connectionId) {
+    return (
+      <GraphExplorationWrapper
+        widgetId={widgetId ?? connectionId}
+        nodes={graphData.nodes ?? []}
+        edges={graphData.edges ?? []}
+        connectionId={connectionId}
+        settings={settings}
+        onChartClick={onChartClick}
+        resultId={resultId}
+        autoFit={autoFit}
+      />
+    );
+  }
+  return (
+    <GraphChart
+      nodes={graphData.nodes ?? []}
+      edges={graphData.edges ?? []}
+      layout={settings.layout as "force" | "circular" | undefined}
+      showLabels={settings.showLabels as boolean | undefined}
+      onNodeSelect={
+        onChartClick
+          ? (ids) => {
+              if (ids.length) onChartClick({ nodeId: ids[0] });
+            }
+          : undefined
+      }
+      autoFit={autoFit}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+    />
+  );
+}
+
+export const graphPlugin = defineChartPlugin({
+  type: "graph",
+  label: "Graph",
+  component: GraphPluginComponent,
+  transform: chartRegistry.graph.transform,
+  transformWithMapping: chartRegistry.graph.transformWithMapping,
+  validate: chartRegistry.graph.validate,
+  compatibleWith: ["neo4j"],
+  stylingTargets: [{ value: "color", label: "Node Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: false,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return Neo4j nodes, relationships, or paths.\n" +
+    "Example: MATCH (n)-[r]->(m) RETURN n, r, m",
+});
diff --git a/app/src/plugins/iframe.tsx b/app/src/plugins/iframe.tsx
new file mode 100644
index 00000000..d42eb3c5
--- /dev/null
+++ b/app/src/plugins/iframe.tsx
@@ -0,0 +1,39 @@
+/**
+ * Iframe widget plugin.
+ *
+ * Embeds an external URL in the dashboard. No query, no data transform.
+ */
+
+import { IframeWidget } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+
+interface PluginComponentProps {
+  settings: Record<string, unknown>;
+}
+
+function IframePluginComponent({ settings }: PluginComponentProps) {
+  return (
+    <IframeWidget
+      url={settings.url as string | undefined}
+      title={settings.iframeTitle as string | undefined}
+      sandbox={settings.sandbox as string | undefined}
+    />
+  );
+}
+
+export const iframePlugin = defineChartPlugin({
+  type: "iframe",
+  label: "iFrame",
+  component: IframePluginComponent,
+  transform: () => null,
+  compatibleWith: ["neo4j", "postgresql"],
+  capabilities: {
+    supportsClickAction: false,
+    supportsStyling: false,
+    isECharts: false,
+    requiresQuery: false,
+  },
+  queryHint:
+    "Iframe widgets embed an external URL — no query required. " +
+    "Use the URL field in the widget settings.",
+});
diff --git a/app/src/plugins/index.ts b/app/src/plugins/index.ts
index d64bfd9e..226f5b3d 100644
--- a/app/src/plugins/index.ts
+++ b/app/src/plugins/index.ts
@@ -8,11 +8,10 @@
  * To add a new chart plugin:
  *   1. Create `app/src/plugins/your-chart.ts` that exports a plugin
  *      via `defineChartPlugin({ ... })`
- *   2. Add `registerPluginFromFile("./your-chart")` here
+ *   2. Add the plugin to the BUILT_IN_PLUGINS array below
  *
- * During the v1.1 plugin migration, charts are moved from the legacy
- * switch statement in chart-renderer.tsx into this registry one by one.
- * Charts not yet migrated continue to work via the switch fallback.
+ * As of PR 4, all chart types are registered here — chart-renderer's
+ * switch statement has been removed and plugin lookup is the only path.
  */
 
 import { pluginRegistry } from "./registry";
@@ -20,8 +19,39 @@ import { markdownPlugin } from "./markdown";
 import { barPlugin } from "./bar";
 import { linePlugin } from "./line";
 import { piePlugin } from "./pie";
+import { singleValuePlugin } from "./single-value";
+import { graphPlugin } from "./graph";
+import { mapPlugin } from "./map";
+import { tablePlugin } from "./table";
+import { parameterSelectPlugin } from "./parameter-select";
+import { jsonPlugin } from "./json";
+import { formPlugin } from "./form";
+import { iframePlugin } from "./iframe";
+import { gaugePlugin } from "./gauge";
+import { sankeyPlugin } from "./sankey";
+import { sunburstPlugin } from "./sunburst";
+import { radarPlugin } from "./radar";
+import { treemapPlugin } from "./treemap";
 
-const BUILT_IN_PLUGINS = [markdownPlugin, barPlugin, linePlugin, piePlugin];
+const BUILT_IN_PLUGINS = [
+  markdownPlugin,
+  barPlugin,
+  linePlugin,
+  piePlugin,
+  singleValuePlugin,
+  graphPlugin,
+  mapPlugin,
+  tablePlugin,
+  parameterSelectPlugin,
+  jsonPlugin,
+  formPlugin,
+  iframePlugin,
+  gaugePlugin,
+  sankeyPlugin,
+  sunburstPlugin,
+  radarPlugin,
+  treemapPlugin,
+];
 
 // Idempotent registration — the first import of this module registers
 // plugins; subsequent imports are no-ops thanks to Node's module cache.
diff --git a/app/src/plugins/json.tsx b/app/src/plugins/json.tsx
new file mode 100644
index 00000000..ff317d41
--- /dev/null
+++ b/app/src/plugins/json.tsx
@@ -0,0 +1,43 @@
+/**
+ * JSON viewer widget plugin.
+ *
+ * Collapsible JSON tree view for raw query results. No click action,
+ * no styling — this is a read-only inspector widget.
+ */
+
+import { JsonViewer } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+}
+
+function JsonPluginComponent({ data, settings }: PluginComponentProps) {
+  return (
+    <div className="h-full overflow-auto">
+      <JsonViewer
+        data={data}
+        initialExpanded={(settings.initialExpanded as number) ?? 2}
+      />
+    </div>
+  );
+}
+
+export const jsonPlugin = defineChartPlugin({
+  type: "json",
+  label: "JSON Viewer",
+  component: JsonPluginComponent,
+  transform: chartRegistry.json.transform,
+  transformWithMapping: chartRegistry.json.transformWithMapping,
+  compatibleWith: ["neo4j", "postgresql"],
+  capabilities: {
+    supportsClickAction: false,
+    supportsStyling: false,
+    isECharts: false,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Returns any query result as a collapsible JSON tree. Any shape works.",
+});
diff --git a/app/src/plugins/map.tsx b/app/src/plugins/map.tsx
new file mode 100644
index 00000000..c12a65c9
--- /dev/null
+++ b/app/src/plugins/map.tsx
@@ -0,0 +1,85 @@
+/**
+ * Map chart plugin.
+ *
+ * Leaflet-based map with markers. Supports click actions and rule-based
+ * styling. Heavy dependency — lazy loaded only when a map widget appears.
+ */
+
+import dynamic from "next/dynamic";
+import type { MapMarker, StylingRule } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+// Leaflet relies on window/document — must be loaded client-side only.
+const MapChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.MapChart })),
+  {
+    ssr: false,
+    loading: () => (
+      <div className="flex h-full w-full items-center justify-center">
+        <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+      </div>
+    ),
+  },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onChartClick?: (point: Record<string, unknown>) => void;
+}
+
+function MapPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onChartClick,
+}: PluginComponentProps) {
+  const markers = (data ?? []) as MapMarker[];
+  return (
+    <MapChart
+      markers={markers}
+      tileLayer={settings.tileLayer as string | undefined}
+      zoom={settings.zoom as number | undefined}
+      minZoom={settings.minZoom as number | undefined}
+      maxZoom={settings.maxZoom as number | undefined}
+      autoFitBounds={settings.autoFitBounds !== false}
+      onMarkerClick={
+        onChartClick
+          ? (m) =>
+              onChartClick({
+                id: m.id,
+                label: m.label,
+                lat: m.lat,
+                lng: m.lng,
+              })
+          : undefined
+      }
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+    />
+  );
+}
+
+export const mapPlugin = defineChartPlugin({
+  type: "map",
+  label: "Map",
+  component: MapPluginComponent,
+  transform: chartRegistry.map.transform,
+  transformWithMapping: chartRegistry.map.transformWithMapping,
+  validate: chartRegistry.map.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Marker Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: false,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return columns with latitude and longitude (names matching lat/lng/lon).\n" +
+    "Example: RETURN name, latitude, longitude",
+});
diff --git a/app/src/plugins/parameter-select.tsx b/app/src/plugins/parameter-select.tsx
new file mode 100644
index 00000000..619c7fdd
--- /dev/null
+++ b/app/src/plugins/parameter-select.tsx
@@ -0,0 +1,74 @@
+/**
+ * Parameter selector widget plugin.
+ *
+ * Interactive input widget that exposes a dashboard parameter — dropdown,
+ * text, date picker, number range, etc. Drives other widgets via the
+ * parameter store. No data transform — the parameter-widget-renderer
+ * handles its own option fetching.
+ */
+
+import { EmptyState } from "@neoboard/components";
+import { ParameterWidgetRenderer } from "@/components/parameter-widget-renderer";
+import type { ParameterType } from "@/stores/parameter-store";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+interface PluginComponentProps {
+  settings: Record<string, unknown>;
+  connectionId?: string;
+  widgetId?: string;
+}
+
+function ParameterSelectPluginComponent({
+  settings,
+  connectionId,
+  widgetId,
+}: PluginComponentProps) {
+  const pName = settings.parameterName as string | undefined;
+  if (!pName) {
+    return (
+      <EmptyState
+        title="No parameter name"
+        description="Configure a parameter name in the widget settings."
+        className="py-6"
+      />
+    );
+  }
+  return (
+    <div className="p-4">
+      <ParameterWidgetRenderer
+        parameterName={pName}
+        parameterType={
+          (settings.parameterType as ParameterType | undefined) ?? "select"
+        }
+        connectionId={connectionId}
+        seedQuery={settings.seedQuery as string | undefined}
+        parentParameterName={settings.parentParameterName as string | undefined}
+        rangeMin={(settings.rangeMin as number | undefined) ?? 0}
+        rangeMax={(settings.rangeMax as number | undefined) ?? 100}
+        rangeStep={(settings.rangeStep as number | undefined) ?? 1}
+        placeholder={(settings.placeholder as string | undefined) || undefined}
+        searchable={(settings.searchable as boolean | undefined) ?? true}
+        widgetId={widgetId}
+      />
+    </div>
+  );
+}
+
+export const parameterSelectPlugin = defineChartPlugin({
+  type: "parameter-select",
+  label: "Parameter Selector",
+  component: ParameterSelectPluginComponent,
+  transform: chartRegistry["parameter-select"].transform,
+  transformWithMapping: chartRegistry["parameter-select"].transformWithMapping,
+  compatibleWith: ["neo4j", "postgresql"],
+  capabilities: {
+    supportsClickAction: false,
+    supportsStyling: false,
+    isECharts: false,
+    requiresQuery: false,
+  },
+  queryHint:
+    "Optional seed query — return a single column of values to populate the\n" +
+    "selector options. Example: RETURN DISTINCT category FROM items",
+});
diff --git a/app/src/plugins/radar.tsx b/app/src/plugins/radar.tsx
new file mode 100644
index 00000000..edca96a4
--- /dev/null
+++ b/app/src/plugins/radar.tsx
@@ -0,0 +1,69 @@
+/**
+ * Radar chart plugin.
+ *
+ * Multi-axis chart comparing several quantitative variables. Supports
+ * rule-based styling but not click actions.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type { RadarChartData, StylingRule } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const RadarChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.RadarChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+}
+
+function RadarPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+}: PluginComponentProps) {
+  const radarData = (data as RadarChartData) ?? {
+    indicators: [],
+    series: [],
+  };
+  return (
+    <RadarChart
+      data={radarData}
+      shape={settings.shape as "polygon" | "circle" | undefined}
+      filled={settings.filled as boolean | undefined}
+      showLegend={settings.showLegend as boolean | undefined}
+      showValues={settings.showValues as boolean | undefined}
+      colorPalette={settings.colorPalette as string | undefined}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const radarPlugin = defineChartPlugin({
+  type: "radar",
+  label: "Radar",
+  component: RadarPluginComponent,
+  transform: chartRegistry.radar.transform,
+  transformWithMapping: chartRegistry.radar.transformWithMapping,
+  validate: chartRegistry.radar.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Area Color" }],
+  capabilities: {
+    supportsClickAction: false,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return either long-format (indicator, value, [series], [max]) or\n" +
+    "wide-format (one column per indicator). Example: RETURN axis, score, series",
+});
diff --git a/app/src/plugins/sankey.tsx b/app/src/plugins/sankey.tsx
new file mode 100644
index 00000000..ce1f558f
--- /dev/null
+++ b/app/src/plugins/sankey.tsx
@@ -0,0 +1,74 @@
+/**
+ * Sankey chart plugin.
+ *
+ * Flow diagram showing how items move from one category to another.
+ * Supports click actions and rule-based styling.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  SankeyChartData,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const SankeyChart = dynamic(
+  () =>
+    import("@neoboard/components").then((m) => ({ default: m.SankeyChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+}
+
+function SankeyPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+}: PluginComponentProps) {
+  const sankeyData = (data as SankeyChartData) ?? { nodes: [], links: [] };
+  return (
+    <SankeyChart
+      data={sankeyData}
+      orient={settings.orient as "horizontal" | "vertical" | undefined}
+      showLabels={settings.showLabels as boolean | undefined}
+      nodeWidth={settings.nodeWidth as number | undefined}
+      nodeGap={settings.nodeGap as number | undefined}
+      colorPalette={settings.colorPalette as string | undefined}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      onClick={onClick}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const sankeyPlugin = defineChartPlugin({
+  type: "sankey",
+  label: "Sankey",
+  component: SankeyPluginComponent,
+  transform: chartRegistry.sankey.transform,
+  transformWithMapping: chartRegistry.sankey.transformWithMapping,
+  validate: chartRegistry.sankey.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Link Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return 3 columns: source, target, value.\n" +
+    "Example: RETURN fromNode AS source, toNode AS target, flow AS value",
+});
diff --git a/app/src/plugins/single-value.tsx b/app/src/plugins/single-value.tsx
new file mode 100644
index 00000000..b53b77f3
--- /dev/null
+++ b/app/src/plugins/single-value.tsx
@@ -0,0 +1,90 @@
+/**
+ * Single-value chart plugin.
+ *
+ * Displays a single scalar value (number or string) with optional prefix,
+ * suffix, title, and number formatting. Supports rule-based styling
+ * (color / backgroundColor) but no click action.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type { StylingRule } from "@neoboard/components";
+import { normalizeValue } from "@/lib/normalize-value";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const SingleValueChart = dynamic(
+  () =>
+    import("@neoboard/components").then((m) => ({
+      default: m.SingleValueChart,
+    })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  colorThresholds?: string;
+}
+
+function SingleValuePluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  colorThresholds,
+}: PluginComponentProps) {
+  const raw = data ?? 0;
+  const val =
+    typeof raw === "number" || typeof raw === "string"
+      ? raw
+      : (normalizeValue(raw) ?? String(raw));
+  return (
+    <SingleValueChart
+      value={
+        typeof val === "number" || typeof val === "string" ? val : String(val)
+      }
+      title={settings.title as string | undefined}
+      prefix={settings.prefix as string | undefined}
+      suffix={settings.suffix as string | undefined}
+      fontSize={settings.fontSize as "sm" | "md" | "lg" | "xl" | undefined}
+      numberFormat={
+        settings.numberFormat as
+          | "plain"
+          | "comma"
+          | "compact"
+          | "percent"
+          | undefined
+      }
+      decimalPlaces={settings.decimalPlaces as number | undefined}
+      colorThresholds={colorThresholds}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+    />
+  );
+}
+
+export const singleValuePlugin = defineChartPlugin({
+  type: "single-value",
+  label: "Single Value",
+  component: SingleValuePluginComponent,
+  transform: chartRegistry["single-value"].transform,
+  transformWithMapping: chartRegistry["single-value"].transformWithMapping,
+  validate: chartRegistry["single-value"].validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [
+    { value: "color", label: "Text Color" },
+    { value: "backgroundColor", label: "Background Color" },
+  ],
+  capabilities: {
+    supportsClickAction: false,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return 1 column with a scalar value (number or string).\n" +
+    "Example: RETURN count(*) AS total",
+});
diff --git a/app/src/plugins/sunburst.tsx b/app/src/plugins/sunburst.tsx
new file mode 100644
index 00000000..bf0be2fb
--- /dev/null
+++ b/app/src/plugins/sunburst.tsx
@@ -0,0 +1,72 @@
+/**
+ * Sunburst chart plugin.
+ *
+ * Hierarchical radial chart — shows nested categories as concentric rings.
+ * Supports click actions and rule-based styling.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  SunburstDataItem,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const SunburstChart = dynamic(
+  () =>
+    import("@neoboard/components").then((m) => ({ default: m.SunburstChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+}
+
+function SunburstPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+}: PluginComponentProps) {
+  return (
+    <SunburstChart
+      data={(data as SunburstDataItem[]) ?? []}
+      showLabels={settings.showLabels as boolean | undefined}
+      sort={settings.sort as "desc" | "asc" | "none" | undefined}
+      highlightOnHover={settings.highlightOnHover as boolean | undefined}
+      colorPalette={settings.colorPalette as string | undefined}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      onClick={onClick}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const sunburstPlugin = defineChartPlugin({
+  type: "sunburst",
+  label: "Sunburst",
+  component: SunburstPluginComponent,
+  transform: chartRegistry.sunburst.transform,
+  transformWithMapping: chartRegistry.sunburst.transformWithMapping,
+  validate: chartRegistry.sunburst.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Segment Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return hierarchical data — either pre-nested with children, or flat rows\n" +
+    "with name/parent/value columns. Example: RETURN name, parent, value",
+});
diff --git a/app/src/plugins/table.tsx b/app/src/plugins/table.tsx
new file mode 100644
index 00000000..6fb99360
--- /dev/null
+++ b/app/src/plugins/table.tsx
@@ -0,0 +1,75 @@
+/**
+ * Table widget plugin.
+ *
+ * Auto-paginated data grid with sorting, filtering, and per-cell styling.
+ * Supports click actions (per-cell) and rule-based styling (backgroundColor,
+ * textColor) plus gradient color scales.
+ */
+
+import type { StylingRule, ColorScaleConfig } from "@neoboard/components";
+import { TableRenderer } from "@/components/table-renderer";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  colorScales?: ColorScaleConfig[];
+  clickableColumns?: string[];
+  onChartClick?: (point: Record<string, unknown>) => void;
+}
+
+function TablePluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  colorScales,
+  clickableColumns,
+  onChartClick,
+}: PluginComponentProps) {
+  return (
+    <TableRenderer
+      data={data}
+      settings={settings}
+      onCellClick={
+        onChartClick
+          ? (info) =>
+              onChartClick({
+                _clickedColumn: info.column,
+                _clickedValue: info.value,
+              })
+          : undefined
+      }
+      clickableColumns={clickableColumns}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      colorScales={colorScales}
+    />
+  );
+}
+
+export const tablePlugin = defineChartPlugin({
+  type: "table",
+  label: "Data Table",
+  component: TablePluginComponent,
+  transform: chartRegistry.table.transform,
+  transformWithMapping: chartRegistry.table.transformWithMapping,
+  validate: chartRegistry.table.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [
+    { value: "backgroundColor", label: "Background Color" },
+    { value: "textColor", label: "Text Color" },
+  ],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: false,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return any tabular data — each column becomes a sortable grid column.\n" +
+    "Example: RETURN name, created_at, status FROM users",
+});
diff --git a/app/src/plugins/treemap.tsx b/app/src/plugins/treemap.tsx
new file mode 100644
index 00000000..a274a97d
--- /dev/null
+++ b/app/src/plugins/treemap.tsx
@@ -0,0 +1,75 @@
+/**
+ * Treemap chart plugin.
+ *
+ * Hierarchical rectangles — each block's area is proportional to its value.
+ * Supports click actions, drilldown, and rule-based styling.
+ */
+
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import type {
+  TreemapDataItem,
+  EChartsClickEvent,
+  StylingRule,
+} from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { chartRegistry } from "@/lib/chart-registry";
+
+const TreemapChart = dynamic(
+  () =>
+    import("@neoboard/components").then((m) => ({ default: m.TreemapChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+interface PluginComponentProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: StylingRule[];
+  paramValues?: Record<string, unknown>;
+  onClick?: (e: EChartsClickEvent) => void;
+}
+
+function TreemapPluginComponent({
+  data,
+  settings,
+  stylingRules,
+  paramValues,
+  onClick,
+}: PluginComponentProps) {
+  return (
+    <TreemapChart
+      data={(data as TreemapDataItem[]) ?? []}
+      showLabels={settings.showLabels as boolean | undefined}
+      showBreadcrumb={settings.showBreadcrumb as boolean | undefined}
+      showValues={settings.showValues as boolean | undefined}
+      colorSaturation={
+        settings.colorSaturation as "low" | "medium" | "high" | undefined
+      }
+      colorPalette={settings.colorPalette as string | undefined}
+      stylingRules={stylingRules}
+      paramValues={paramValues}
+      onClick={onClick}
+      colorblindMode={settings.colorblindMode as boolean | undefined}
+    />
+  );
+}
+
+export const treemapPlugin = defineChartPlugin({
+  type: "treemap",
+  label: "Treemap",
+  component: TreemapPluginComponent,
+  transform: chartRegistry.treemap.transform,
+  transformWithMapping: chartRegistry.treemap.transformWithMapping,
+  validate: chartRegistry.treemap.validate,
+  compatibleWith: ["neo4j", "postgresql"],
+  stylingTargets: [{ value: "color", label: "Block Color" }],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: true,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint:
+    "Return hierarchical data — either pre-nested with children, or flat rows\n" +
+    "with name/parent/value columns. Example: RETURN name, parent, value",
+});

From d7972f57c48d7ebee719a40d87e0242b10c93a5c Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 01:27:30 +0200
Subject: [PATCH 32/36] fix: switch from Turbopack to webpack for dev/E2E
 (#220)

Turbopack (Next.js 16 default) doesn't correctly handle CJS require()
for transpiled monorepo packages, causing createConnectionModule to
be undefined at runtime. This breaks all database queries.

Changes:
- app/package.json: `next dev --webpack` instead of `--turbopack`
- app/e2e/global-setup.ts: explicit `--webpack` for local E2E dev mode
- app/next.config.ts: add @neoboard/connection to transpilePackages,
  remove it from serverExternalPackages (it's an internal package)
- app/src/lib/connection-adapter.ts: clean require() with docs

E2E tests now pass locally (table, single-value, JSON, Neo4j bar
chart verified). The --webpack flag can be removed once Turbopack
fixes transpilePackages for CJS monorepo packages.

See: https://github.com/vercel/next.js/issues/85316

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/e2e/global-setup.ts           |  4 +++-
 app/next.config.ts                |  9 ++++++--
 app/package.json                  |  2 +-
 app/src/lib/connection-adapter.ts | 34 +++++++++++++++----------------
 4 files changed, 28 insertions(+), 21 deletions(-)

diff --git a/app/e2e/global-setup.ts b/app/e2e/global-setup.ts
index 9f85c812..58d7ecfb 100644
--- a/app/e2e/global-setup.ts
+++ b/app/e2e/global-setup.ts
@@ -249,7 +249,9 @@ export default async function globalSetup() {
     `⏳ Starting Next.js ${serverCmd} server on port ${serverPort}...`,
   );
   const args = ["next", serverCmd, "--port", String(serverPort)];
-  if (serverCmd === "dev") args.push("--turbopack");
+  // Use webpack explicitly — Turbopack (Next.js 16 default) doesn't correctly
+  // resolve CJS/ESM interop for the @neoboard/connection package at runtime.
+  if (serverCmd === "dev") args.push("--webpack");
   const server = spawn("npx", args, {
     cwd: appDir,
     stdio: "pipe",
diff --git a/app/next.config.ts b/app/next.config.ts
index 5d9aef6b..963a7024 100644
--- a/app/next.config.ts
+++ b/app/next.config.ts
@@ -24,8 +24,13 @@ const nextConfig: NextConfig = {
   // Enable source maps in production for E2E coverage collection (nextcov).
   productionBrowserSourceMaps: process.env.E2E_COVERAGE === "1",
   outputFileTracingRoot: resolve(import.meta.dirname, ".."),
-  transpilePackages: ["@neoboard/components"],
-  serverExternalPackages: ["connection", "postgres", "pg"],
+  transpilePackages: ["@neoboard/components", "@neoboard/connection"],
+  serverExternalPackages: [
+    "postgres",
+    "pg",
+    "neo4j-driver",
+    "neo4j-driver-core",
+  ],
   webpack: (config, { isServer }) => {
     if (isServer) {
       // The instrumentation file is compiled in a separate webpack pass that does
diff --git a/app/package.json b/app/package.json
index 94eb47d1..018ca7d1 100644
--- a/app/package.json
+++ b/app/package.json
@@ -3,7 +3,7 @@
   "version": "0.0.1",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "next dev --webpack",
     "build": "next build --webpack",
     "start": "next start",
     "lint": "next lint",
diff --git a/app/src/lib/connection-adapter.ts b/app/src/lib/connection-adapter.ts
index 6ce7a9c1..734da85a 100644
--- a/app/src/lib/connection-adapter.ts
+++ b/app/src/lib/connection-adapter.ts
@@ -1,27 +1,27 @@
 /**
- * Thin adapter that re-exports connection package symbols.
+ * Thin adapter that re-exports connection package symbols using CJS require().
  *
- * The connection package ships as TypeScript source — its type definitions
- * reference internal neo4j-driver-core paths that don't resolve under the
- * app's strict tsconfig.  We use Node's `createRequire` to load the
- * modules at runtime, keeping the type checker opaque to the package
- * internals while ensuring Turbopack doesn't try to bundle them.
+ * The connection package (@neoboard/connection) ships as TypeScript source.
+ * It's listed in `transpilePackages` in next.config.ts so webpack compiles
+ * it as part of the app build — no separate build step needed.
+ *
+ * We use require() (not ESM import) to keep the type checker opaque to the
+ * connection package's internal types which reference neo4j-driver-core
+ * paths that don't resolve under the app's strict tsconfig.
+ *
+ * IMPORTANT: This requires `--webpack` flag (not Turbopack) because
+ * Turbopack doesn't correctly handle CJS require() for transpiled packages.
+ * See: https://github.com/vercel/next.js/issues/85316
  *
  * Isolating the require() calls here also makes query-executor.ts fully
  * mockable in Vitest (vi.mock("./connection-adapter", …)).
  */
 
-import { createRequire } from "node:module";
-
-const require_ = createRequire(import.meta.url);
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-const factory: any = require_("@neoboard/connection/src/adapters/factory");
-const interfaces: any = require_(
-  "@neoboard/connection/src/generalized/interfaces",
-);
-const config: any = require_("@neoboard/connection/src/ConnectionModuleConfig");
-/* eslint-enable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any */
+const factory: any = require("@neoboard/connection/src/adapters/factory");
+const interfaces: any = require("@neoboard/connection/src/generalized/interfaces");
+const config: any = require("@neoboard/connection/src/ConnectionModuleConfig");
+/* eslint-enable @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any */
 
 export const createConnectionModule: (
   type: number,

From 262e4a30ca34b34d9a1651e6f5368a051b47fe65 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 11:28:06 +0200
Subject: [PATCH 33/36] ci: re-trigger flaky graph E2E


From a87a3dbc116b90b1abe42288a35df60e146fa3b6 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 11:40:22 +0200
Subject: [PATCH 34/36] =?UTF-8?q?refactor:=20unify=20plugin=20callback=20?=
 =?UTF-8?q?=E2=80=94=20single=20onChartClick,=20shared=20PluginProps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New: plugins/utils.ts — PluginProps type + useEChartsClick() hook
- All 16 plugins use PluginProps (no more per-plugin interfaces)
- chart-renderer passes only onChartClick (removed handleEChartsClick)
- ECharts plugins wrap onChartClick via useEChartsClick() internally
- Removed unused useMemo, EChartsClickEvent imports from renderer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/src/components/chart-renderer.tsx | 31 +++------------
 app/src/plugins/bar.tsx               | 27 ++++---------
 app/src/plugins/form.tsx              | 13 +------
 app/src/plugins/gauge.tsx             | 22 +++--------
 app/src/plugins/graph.tsx             | 17 ++------
 app/src/plugins/iframe.tsx            |  7 +---
 app/src/plugins/json.tsx              |  8 +---
 app/src/plugins/line.tsx              | 23 +++--------
 app/src/plugins/map.tsx               | 13 ++-----
 app/src/plugins/markdown.tsx          |  7 +---
 app/src/plugins/parameter-select.tsx  |  9 +----
 app/src/plugins/pie.tsx               | 23 +++--------
 app/src/plugins/radar.tsx             | 12 ++----
 app/src/plugins/sankey.tsx            | 22 +++--------
 app/src/plugins/single-value.tsx      | 13 ++-----
 app/src/plugins/sunburst.tsx          | 22 +++--------
 app/src/plugins/table.tsx             | 17 ++------
 app/src/plugins/treemap.tsx           | 22 +++--------
 app/src/plugins/utils.ts              | 56 +++++++++++++++++++++++++++
 19 files changed, 131 insertions(+), 233 deletions(-)
 create mode 100644 app/src/plugins/utils.ts

diff --git a/app/src/components/chart-renderer.tsx b/app/src/components/chart-renderer.tsx
index be2c8f60..0cb56e44 100644
--- a/app/src/components/chart-renderer.tsx
+++ b/app/src/components/chart-renderer.tsx
@@ -1,16 +1,12 @@
 "use client";
 
-import React, { useMemo } from "react";
+import React from "react";
 import { AlertCircle } from "lucide-react";
 import type { ChartType } from "@/lib/chart-registry";
 import { pluginRegistry } from "@/plugins";
 import { ChartErrorBoundary } from "./chart-error-boundary";
 import { EmptyState } from "@neoboard/components";
-import type {
-  EChartsClickEvent,
-  StylingRule,
-  ColorScaleConfig,
-} from "@neoboard/components";
+import type { StylingRule, ColorScaleConfig } from "@neoboard/components";
 
 /** Styling-related props grouped together. */
 export interface ChartStylingProps {
@@ -74,31 +70,15 @@ function ChartRendererInner({
       ? settings.colorThresholds
       : undefined;
 
-  const handleEChartsClick = useMemo(() => {
-    if (!onChartClick) return undefined;
-    return (e: EChartsClickEvent) => {
-      // Enrich the click point with the original data row so that
-      // column-name source fields (e.g. "revenue") resolve correctly
-      // in click action rules — not just ECharts built-in fields.
-      const row = Array.isArray(data)
-        ? (data[e.dataIndex] as Record<string, unknown> | undefined)
-        : undefined;
-      onChartClick({
-        ...(row ?? {}),
-        name: e.name,
-        value: e.value,
-        seriesName: e.seriesName,
-        dataIndex: e.dataIndex,
-      });
-    };
-  }, [onChartClick, data]);
-
   // Plugin-driven rendering — every chart type is registered as a plugin
   // in app/src/plugins/. The plugin's component receives the full set of
   // props; it picks the ones it needs.
   const plugin = pluginRegistry.get(type);
   if (plugin) {
     const PluginComponent = plugin.component;
+    // Pass onChartClick (the raw row-level callback) to all plugins.
+    // ECharts-based plugins wrap it in their own ECharts event handler
+    // internally — this keeps the plugin contract to ONE callback.
     return (
       <PluginComponent
         data={data}
@@ -106,7 +86,6 @@ function ChartRendererInner({
         stylingRules={stylingRules}
         paramValues={paramValues}
         colorScales={colorScales}
-        onClick={handleEChartsClick}
         onChartClick={onChartClick}
         connectionId={connectionId}
         widgetId={widgetId}
diff --git a/app/src/plugins/bar.tsx b/app/src/plugins/bar.tsx
index 02068616..6f3df728 100644
--- a/app/src/plugins/bar.tsx
+++ b/app/src/plugins/bar.tsx
@@ -7,37 +7,26 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  BarChartDataPoint,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { BarChartDataPoint, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
-// Charts use ECharts (browser APIs) — must be loaded client-side only
 const BarChart = dynamic(
   () => import("@neoboard/components").then((m) => ({ default: m.BarChart })),
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-  colorThresholds?: string;
-}
-
 function BarPluginComponent({
   data,
   settings,
+  onChartClick,
+  colorThresholds,
   stylingRules,
   paramValues,
-  onClick,
-  colorThresholds,
-}: PluginComponentProps) {
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
+
   return (
     <BarChart
       data={(data as BarChartDataPoint[]) ?? []}
@@ -55,7 +44,7 @@ function BarPluginComponent({
       axisLabelRotation={settings.axisLabelRotation as number | undefined}
       referenceLines={settings.referenceLines as string | undefined}
       colorThresholds={colorThresholds}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       onClick={onClick}
       enableDataZoom={settings.enableDataZoom as boolean | undefined}
diff --git a/app/src/plugins/form.tsx b/app/src/plugins/form.tsx
index d84ea3ff..a56995e2 100644
--- a/app/src/plugins/form.tsx
+++ b/app/src/plugins/form.tsx
@@ -7,18 +7,9 @@
 
 import { FormWidgetRenderer } from "@/components/form-widget-renderer";
 import { defineChartPlugin } from "./registry";
+import { type PluginProps } from "./utils";
 
-interface PluginComponentProps {
-  settings: Record<string, unknown>;
-  connectionId?: string;
-  query?: string;
-}
-
-function FormPluginComponent({
-  settings,
-  connectionId,
-  query,
-}: PluginComponentProps) {
+function FormPluginComponent({ settings, connectionId, query }: PluginProps) {
   return (
     <FormWidgetRenderer
       connectionId={connectionId ?? ""}
diff --git a/app/src/plugins/gauge.tsx b/app/src/plugins/gauge.tsx
index 3c9d4ba1..6ff817c0 100644
--- a/app/src/plugins/gauge.tsx
+++ b/app/src/plugins/gauge.tsx
@@ -7,34 +7,24 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  GaugeDataPoint,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { GaugeDataPoint, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
 const GaugeChart = dynamic(
   () => import("@neoboard/components").then((m) => ({ default: m.GaugeChart })),
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-}
-
 function GaugePluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-  onClick,
-}: PluginComponentProps) {
+  onChartClick,
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
   return (
     <GaugeChart
       data={(data as GaugeDataPoint[]) ?? []}
@@ -46,7 +36,7 @@ function GaugePluginComponent({
       startAngle={settings.startAngle as number | undefined}
       endAngle={settings.endAngle as number | undefined}
       colorPalette={settings.colorPalette as string | undefined}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       colorblindMode={settings.colorblindMode as boolean | undefined}
       onClick={onClick}
diff --git a/app/src/plugins/graph.tsx b/app/src/plugins/graph.tsx
index 30af9ad5..4c6235ea 100644
--- a/app/src/plugins/graph.tsx
+++ b/app/src/plugins/graph.tsx
@@ -13,6 +13,7 @@ import type { GraphNode, GraphEdge, StylingRule } from "@neoboard/components";
 import { GraphExplorationWrapper } from "@/components/graph-exploration-wrapper";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { type PluginProps } from "./utils";
 
 // NVL (WebGL) is heavy — lazy load so it's only bundled when a graph widget renders.
 const GraphChart = dynamic(
@@ -20,18 +21,6 @@ const GraphChart = dynamic(
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onChartClick?: (point: Record<string, unknown>) => void;
-  connectionId?: string;
-  widgetId?: string;
-  resultId?: string;
-  autoFit?: boolean;
-}
-
 function GraphPluginComponent({
   data,
   settings,
@@ -42,7 +31,7 @@ function GraphPluginComponent({
   widgetId,
   resultId,
   autoFit,
-}: PluginComponentProps) {
+}: PluginProps) {
   const graphData = (data ?? { nodes: [], edges: [] }) as {
     nodes: GraphNode[];
     edges: GraphEdge[];
@@ -75,7 +64,7 @@ function GraphPluginComponent({
           : undefined
       }
       autoFit={autoFit}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
     />
   );
diff --git a/app/src/plugins/iframe.tsx b/app/src/plugins/iframe.tsx
index d42eb3c5..455ccba3 100644
--- a/app/src/plugins/iframe.tsx
+++ b/app/src/plugins/iframe.tsx
@@ -6,12 +6,9 @@
 
 import { IframeWidget } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
+import { type PluginProps } from "./utils";
 
-interface PluginComponentProps {
-  settings: Record<string, unknown>;
-}
-
-function IframePluginComponent({ settings }: PluginComponentProps) {
+function IframePluginComponent({ settings }: PluginProps) {
   return (
     <IframeWidget
       url={settings.url as string | undefined}
diff --git a/app/src/plugins/json.tsx b/app/src/plugins/json.tsx
index ff317d41..00016c0c 100644
--- a/app/src/plugins/json.tsx
+++ b/app/src/plugins/json.tsx
@@ -8,13 +8,9 @@
 import { JsonViewer } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { type PluginProps } from "./utils";
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-}
-
-function JsonPluginComponent({ data, settings }: PluginComponentProps) {
+function JsonPluginComponent({ data, settings }: PluginProps) {
   return (
     <div className="h-full overflow-auto">
       <JsonViewer
diff --git a/app/src/plugins/line.tsx b/app/src/plugins/line.tsx
index 568b867c..69ce0a06 100644
--- a/app/src/plugins/line.tsx
+++ b/app/src/plugins/line.tsx
@@ -7,36 +7,25 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  LineChartDataPoint,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { LineChartDataPoint, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
 const LineChart = dynamic(
   () => import("@neoboard/components").then((m) => ({ default: m.LineChart })),
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-  colorThresholds?: string;
-}
-
 function LinePluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-  onClick,
+  onChartClick,
   colorThresholds,
-}: PluginComponentProps) {
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
   // Parse comma-separated rightAxisSeries string into string array
   const rightAxisSeriesRaw = settings.rightAxisSeries as string | undefined;
   const rightAxisSeries = rightAxisSeriesRaw
@@ -64,7 +53,7 @@ function LinePluginComponent({
       endLabel={settings.endLabel as boolean | undefined}
       referenceLines={settings.referenceLines as string | undefined}
       colorThresholds={colorThresholds}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       onClick={onClick}
       enableDataZoom={settings.enableDataZoom as boolean | undefined}
diff --git a/app/src/plugins/map.tsx b/app/src/plugins/map.tsx
index c12a65c9..ed3da9d4 100644
--- a/app/src/plugins/map.tsx
+++ b/app/src/plugins/map.tsx
@@ -9,6 +9,7 @@ import dynamic from "next/dynamic";
 import type { MapMarker, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { type PluginProps } from "./utils";
 
 // Leaflet relies on window/document — must be loaded client-side only.
 const MapChart = dynamic(
@@ -23,21 +24,13 @@ const MapChart = dynamic(
   },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onChartClick?: (point: Record<string, unknown>) => void;
-}
-
 function MapPluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
   onChartClick,
-}: PluginComponentProps) {
+}: PluginProps) {
   const markers = (data ?? []) as MapMarker[];
   return (
     <MapChart
@@ -58,7 +51,7 @@ function MapPluginComponent({
               })
           : undefined
       }
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
     />
   );
diff --git a/app/src/plugins/markdown.tsx b/app/src/plugins/markdown.tsx
index d87fbabb..47273694 100644
--- a/app/src/plugins/markdown.tsx
+++ b/app/src/plugins/markdown.tsx
@@ -8,6 +8,7 @@
 
 import { MarkdownWidget } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
+import { type PluginProps } from "./utils";
 
 interface MarkdownWidgetProps {
   content?: string;
@@ -18,11 +19,7 @@ interface MarkdownWidgetProps {
  * renders the MarkdownWidget. The plugin contract passes the full
  * settings object to the component as `settings` prop.
  */
-function MarkdownPluginComponent({
-  settings,
-}: {
-  settings: Record<string, unknown>;
-}) {
+function MarkdownPluginComponent({ settings }: PluginProps) {
   const props: MarkdownWidgetProps = {
     content: settings.content as string | undefined,
   };
diff --git a/app/src/plugins/parameter-select.tsx b/app/src/plugins/parameter-select.tsx
index 619c7fdd..bf4d3a76 100644
--- a/app/src/plugins/parameter-select.tsx
+++ b/app/src/plugins/parameter-select.tsx
@@ -12,18 +12,13 @@ import { ParameterWidgetRenderer } from "@/components/parameter-widget-renderer"
 import type { ParameterType } from "@/stores/parameter-store";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
-
-interface PluginComponentProps {
-  settings: Record<string, unknown>;
-  connectionId?: string;
-  widgetId?: string;
-}
+import { type PluginProps } from "./utils";
 
 function ParameterSelectPluginComponent({
   settings,
   connectionId,
   widgetId,
-}: PluginComponentProps) {
+}: PluginProps) {
   const pName = settings.parameterName as string | undefined;
   if (!pName) {
     return (
diff --git a/app/src/plugins/pie.tsx b/app/src/plugins/pie.tsx
index f0366a3f..05f009ca 100644
--- a/app/src/plugins/pie.tsx
+++ b/app/src/plugins/pie.tsx
@@ -7,36 +7,25 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  PieChartDataPoint,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { PieChartDataPoint, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
 const PieChart = dynamic(
   () => import("@neoboard/components").then((m) => ({ default: m.PieChart })),
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-  colorThresholds?: string;
-}
-
 function PiePluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-  onClick,
+  onChartClick,
   colorThresholds,
-}: PluginComponentProps) {
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
   return (
     <PieChart
       data={(data as PieChartDataPoint[]) ?? []}
@@ -52,7 +41,7 @@ function PiePluginComponent({
       topN={settings.topN as number | undefined}
       donutCenterText={settings.donutCenterText as string | undefined}
       colorThresholds={colorThresholds}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       onClick={onClick}
       colorPalette={settings.colorPalette as string | undefined}
diff --git a/app/src/plugins/radar.tsx b/app/src/plugins/radar.tsx
index edca96a4..a49af574 100644
--- a/app/src/plugins/radar.tsx
+++ b/app/src/plugins/radar.tsx
@@ -10,25 +10,19 @@ import { Skeleton } from "@neoboard/components";
 import type { RadarChartData, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { type PluginProps } from "./utils";
 
 const RadarChart = dynamic(
   () => import("@neoboard/components").then((m) => ({ default: m.RadarChart })),
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-}
-
 function RadarPluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-}: PluginComponentProps) {
+}: PluginProps) {
   const radarData = (data as RadarChartData) ?? {
     indicators: [],
     series: [],
@@ -41,7 +35,7 @@ function RadarPluginComponent({
       showLegend={settings.showLegend as boolean | undefined}
       showValues={settings.showValues as boolean | undefined}
       colorPalette={settings.colorPalette as string | undefined}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       colorblindMode={settings.colorblindMode as boolean | undefined}
     />
diff --git a/app/src/plugins/sankey.tsx b/app/src/plugins/sankey.tsx
index ce1f558f..dff40f85 100644
--- a/app/src/plugins/sankey.tsx
+++ b/app/src/plugins/sankey.tsx
@@ -7,13 +7,10 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  SankeyChartData,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { SankeyChartData, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
 const SankeyChart = dynamic(
   () =>
@@ -21,21 +18,14 @@ const SankeyChart = dynamic(
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-}
-
 function SankeyPluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-  onClick,
-}: PluginComponentProps) {
+  onChartClick,
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
   const sankeyData = (data as SankeyChartData) ?? { nodes: [], links: [] };
   return (
     <SankeyChart
@@ -45,7 +35,7 @@ function SankeyPluginComponent({
       nodeWidth={settings.nodeWidth as number | undefined}
       nodeGap={settings.nodeGap as number | undefined}
       colorPalette={settings.colorPalette as string | undefined}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       onClick={onClick}
       colorblindMode={settings.colorblindMode as boolean | undefined}
diff --git a/app/src/plugins/single-value.tsx b/app/src/plugins/single-value.tsx
index b53b77f3..12ac0764 100644
--- a/app/src/plugins/single-value.tsx
+++ b/app/src/plugins/single-value.tsx
@@ -12,6 +12,7 @@ import type { StylingRule } from "@neoboard/components";
 import { normalizeValue } from "@/lib/normalize-value";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { type PluginProps } from "./utils";
 
 const SingleValueChart = dynamic(
   () =>
@@ -21,21 +22,13 @@ const SingleValueChart = dynamic(
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  colorThresholds?: string;
-}
-
 function SingleValuePluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
   colorThresholds,
-}: PluginComponentProps) {
+}: PluginProps) {
   const raw = data ?? 0;
   const val =
     typeof raw === "number" || typeof raw === "string"
@@ -60,7 +53,7 @@ function SingleValuePluginComponent({
       }
       decimalPlaces={settings.decimalPlaces as number | undefined}
       colorThresholds={colorThresholds}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
     />
   );
diff --git a/app/src/plugins/sunburst.tsx b/app/src/plugins/sunburst.tsx
index bf0be2fb..276912e3 100644
--- a/app/src/plugins/sunburst.tsx
+++ b/app/src/plugins/sunburst.tsx
@@ -7,13 +7,10 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  SunburstDataItem,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { SunburstDataItem, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
 const SunburstChart = dynamic(
   () =>
@@ -21,21 +18,14 @@ const SunburstChart = dynamic(
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-}
-
 function SunburstPluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-  onClick,
-}: PluginComponentProps) {
+  onChartClick,
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
   return (
     <SunburstChart
       data={(data as SunburstDataItem[]) ?? []}
@@ -43,7 +33,7 @@ function SunburstPluginComponent({
       sort={settings.sort as "desc" | "asc" | "none" | undefined}
       highlightOnHover={settings.highlightOnHover as boolean | undefined}
       colorPalette={settings.colorPalette as string | undefined}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       onClick={onClick}
       colorblindMode={settings.colorblindMode as boolean | undefined}
diff --git a/app/src/plugins/table.tsx b/app/src/plugins/table.tsx
index 6fb99360..738ac9db 100644
--- a/app/src/plugins/table.tsx
+++ b/app/src/plugins/table.tsx
@@ -10,16 +10,7 @@ import type { StylingRule, ColorScaleConfig } from "@neoboard/components";
 import { TableRenderer } from "@/components/table-renderer";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
-
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  colorScales?: ColorScaleConfig[];
-  clickableColumns?: string[];
-  onChartClick?: (point: Record<string, unknown>) => void;
-}
+import { type PluginProps } from "./utils";
 
 function TablePluginComponent({
   data,
@@ -29,7 +20,7 @@ function TablePluginComponent({
   colorScales,
   clickableColumns,
   onChartClick,
-}: PluginComponentProps) {
+}: PluginProps) {
   return (
     <TableRenderer
       data={data}
@@ -44,9 +35,9 @@ function TablePluginComponent({
           : undefined
       }
       clickableColumns={clickableColumns}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
-      colorScales={colorScales}
+      colorScales={colorScales as ColorScaleConfig[] | undefined}
     />
   );
 }
diff --git a/app/src/plugins/treemap.tsx b/app/src/plugins/treemap.tsx
index a274a97d..a262c8d5 100644
--- a/app/src/plugins/treemap.tsx
+++ b/app/src/plugins/treemap.tsx
@@ -7,13 +7,10 @@
 
 import dynamic from "next/dynamic";
 import { Skeleton } from "@neoboard/components";
-import type {
-  TreemapDataItem,
-  EChartsClickEvent,
-  StylingRule,
-} from "@neoboard/components";
+import type { TreemapDataItem, StylingRule } from "@neoboard/components";
 import { defineChartPlugin } from "./registry";
 import { chartRegistry } from "@/lib/chart-registry";
+import { useEChartsClick, type PluginProps } from "./utils";
 
 const TreemapChart = dynamic(
   () =>
@@ -21,21 +18,14 @@ const TreemapChart = dynamic(
   { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
 );
 
-interface PluginComponentProps {
-  data: unknown;
-  settings: Record<string, unknown>;
-  stylingRules?: StylingRule[];
-  paramValues?: Record<string, unknown>;
-  onClick?: (e: EChartsClickEvent) => void;
-}
-
 function TreemapPluginComponent({
   data,
   settings,
   stylingRules,
   paramValues,
-  onClick,
-}: PluginComponentProps) {
+  onChartClick,
+}: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
   return (
     <TreemapChart
       data={(data as TreemapDataItem[]) ?? []}
@@ -46,7 +36,7 @@ function TreemapPluginComponent({
         settings.colorSaturation as "low" | "medium" | "high" | undefined
       }
       colorPalette={settings.colorPalette as string | undefined}
-      stylingRules={stylingRules}
+      stylingRules={stylingRules as StylingRule[] | undefined}
       paramValues={paramValues}
       onClick={onClick}
       colorblindMode={settings.colorblindMode as boolean | undefined}
diff --git a/app/src/plugins/utils.ts b/app/src/plugins/utils.ts
new file mode 100644
index 00000000..8d5d9218
--- /dev/null
+++ b/app/src/plugins/utils.ts
@@ -0,0 +1,56 @@
+/**
+ * Shared utilities for chart plugins.
+ */
+
+import { useMemo } from "react";
+import type { EChartsClickEvent } from "@neoboard/components";
+
+/**
+ * Standard plugin component props passed by chart-renderer.tsx.
+ * Each plugin picks the subset it needs.
+ */
+export interface PluginProps {
+  data: unknown;
+  settings: Record<string, unknown>;
+  stylingRules?: unknown[];
+  paramValues?: Record<string, unknown>;
+  colorScales?: unknown[];
+  onChartClick?: (point: Record<string, unknown>) => void;
+  connectionId?: string;
+  widgetId?: string;
+  resultId?: string;
+  query?: string;
+  autoFit?: boolean;
+  clickableColumns?: string[];
+  colorThresholds?: string;
+}
+
+/**
+ * Creates an ECharts-compatible onClick handler from the plugin's
+ * raw `onChartClick` callback. Enriches the ECharts event with the
+ * original data row so column-name source fields resolve correctly.
+ *
+ * Usage inside an ECharts plugin component:
+ *   const onClick = useEChartsClick(onChartClick, data);
+ *   <BarChart onClick={onClick} ... />
+ */
+export function useEChartsClick(
+  onChartClick: ((point: Record<string, unknown>) => void) | undefined,
+  data: unknown,
+): ((e: EChartsClickEvent) => void) | undefined {
+  return useMemo(() => {
+    if (!onChartClick) return undefined;
+    return (e: EChartsClickEvent) => {
+      const row = Array.isArray(data)
+        ? (data[e.dataIndex] as Record<string, unknown> | undefined)
+        : undefined;
+      onChartClick({
+        ...(row ?? {}),
+        name: e.name,
+        value: e.value,
+        seriesName: e.seriesName,
+        dataIndex: e.dataIndex,
+      });
+    };
+  }, [onChartClick, data]);
+}

From 184593f9dbeddfca56e8bc147ae9048b18b63e72 Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 11:54:00 +0200
Subject: [PATCH 35/36] feat(connection): connector plugin registry +
 neo4j/postgres plugins (#219)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First PR in the connector plugin system. Adds the plugin contract,
registry, and built-in plugins — without changing any existing code
paths.

New files:
- connection/src/generalized/connector-plugin.ts — ConnectorPlugin
  interface + createConnectorRegistry()
- connection/src/neo4j/plugin.ts — neo4jPlugin
- connection/src/postgresql/plugin.ts — postgresPlugin
- connection/src/connector-registry.ts — global singleton with
  auto-registration, createConnectionModule(), getAllConnectors()
- connection/__tests__/connector-registry.test.ts — 15 tests

Plugin contract:
  type, label, category, createModule, supportsGraphData,
  supportsWrite, queryLanguage, allowedProtocols,
  uriPlaceholder, databasePlaceholder

Registry: register/get/has/getAll/getTypes + validation

Closes #219

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../__tests__/connector-registry.test.ts      | 148 ++++++++++++++++++
 connection/src/connector-registry.ts          |  71 +++++++++
 .../src/generalized/connector-plugin.ts       | 120 ++++++++++++++
 connection/src/neo4j/plugin.ts                |  36 +++++
 connection/src/postgresql/plugin.ts           |  29 ++++
 5 files changed, 404 insertions(+)
 create mode 100644 connection/__tests__/connector-registry.test.ts
 create mode 100644 connection/src/connector-registry.ts
 create mode 100644 connection/src/generalized/connector-plugin.ts
 create mode 100644 connection/src/neo4j/plugin.ts
 create mode 100644 connection/src/postgresql/plugin.ts

diff --git a/connection/__tests__/connector-registry.test.ts b/connection/__tests__/connector-registry.test.ts
new file mode 100644
index 00000000..b69fcc81
--- /dev/null
+++ b/connection/__tests__/connector-registry.test.ts
@@ -0,0 +1,148 @@
+import {
+  createConnectorRegistry,
+  type ConnectorPlugin,
+} from "../src/generalized/connector-plugin";
+
+// ---------------------------------------------------------------------------
+// Fixture
+// ---------------------------------------------------------------------------
+
+const fakeModule = { runQuery: jest.fn(), checkConnection: jest.fn() };
+
+const makePlugin = (
+  overrides: Partial<ConnectorPlugin> = {},
+): ConnectorPlugin => ({
+  type: "test-db",
+  label: "Test DB",
+  category: "database",
+  createModule: () => fakeModule as any,
+  ...overrides,
+});
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+describe("createConnectorRegistry", () => {
+  it("registers and retrieves a plugin by type", () => {
+    const reg = createConnectorRegistry();
+    const plugin = makePlugin();
+    reg.register(plugin);
+    expect(reg.get("test-db")).toBe(plugin);
+  });
+
+  it("returns undefined for unknown type", () => {
+    const reg = createConnectorRegistry();
+    expect(reg.get("unknown")).toBeUndefined();
+  });
+
+  it("has() returns true for registered types", () => {
+    const reg = createConnectorRegistry();
+    reg.register(makePlugin());
+    expect(reg.has("test-db")).toBe(true);
+    expect(reg.has("other")).toBe(false);
+  });
+
+  it("getAll() returns all registered plugins", () => {
+    const reg = createConnectorRegistry();
+    reg.register(makePlugin({ type: "a", label: "A" }));
+    reg.register(makePlugin({ type: "b", label: "B" }));
+    expect(reg.getAll()).toHaveLength(2);
+  });
+
+  it("getTypes() returns type strings", () => {
+    const reg = createConnectorRegistry();
+    reg.register(makePlugin({ type: "neo4j", label: "Neo4j" }));
+    reg.register(makePlugin({ type: "pg", label: "PostgreSQL" }));
+    expect(reg.getTypes()).toEqual(["neo4j", "pg"]);
+  });
+
+  it("throws on duplicate registration", () => {
+    const reg = createConnectorRegistry();
+    reg.register(makePlugin());
+    expect(() => reg.register(makePlugin())).toThrow(/already registered/);
+  });
+
+  it("throws when type is empty", () => {
+    const reg = createConnectorRegistry();
+    expect(() => reg.register(makePlugin({ type: "" }))).toThrow(
+      /type is required/,
+    );
+  });
+
+  it("throws when label is empty", () => {
+    const reg = createConnectorRegistry();
+    expect(() => reg.register(makePlugin({ label: "" }))).toThrow(
+      /label is required/,
+    );
+  });
+
+  it("throws when createModule is not a function", () => {
+    const reg = createConnectorRegistry();
+    expect(() =>
+      reg.register(makePlugin({ createModule: "nope" as any })),
+    ).toThrow(/createModule must be a function/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Built-in plugins
+// ---------------------------------------------------------------------------
+
+describe("built-in connector plugins", () => {
+  it("neo4j plugin has correct type and category", () => {
+    const { neo4jPlugin } = require("../src/neo4j/plugin");
+    expect(neo4jPlugin.type).toBe("neo4j");
+    expect(neo4jPlugin.category).toBe("graph");
+    expect(neo4jPlugin.supportsGraphData).toBe(true);
+    expect(neo4jPlugin.queryLanguage).toBe("cypher");
+  });
+
+  it("postgresql plugin has correct type and category", () => {
+    const { postgresPlugin } = require("../src/postgresql/plugin");
+    expect(postgresPlugin.type).toBe("postgresql");
+    expect(postgresPlugin.category).toBe("database");
+    expect(postgresPlugin.supportsGraphData).toBe(false);
+    expect(postgresPlugin.queryLanguage).toBe("sql");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Global registry (auto-registered)
+// ---------------------------------------------------------------------------
+
+describe("global connector registry", () => {
+  it("has neo4j and postgresql registered on import", () => {
+    const { connectorRegistry } = require("../src/connector-registry");
+    expect(connectorRegistry.has("neo4j")).toBe(true);
+    expect(connectorRegistry.has("postgresql")).toBe(true);
+  });
+
+  it("getAll() returns both built-in connectors", () => {
+    const { getAllConnectors } = require("../src/connector-registry");
+    const all = getAllConnectors();
+    expect(all).toHaveLength(2);
+    expect(all.map((c: any) => c.type).sort()).toEqual(["neo4j", "postgresql"]);
+  });
+
+  it("createConnectionModule() delegates to the correct plugin", () => {
+    const { createConnectionModule } = require("../src/connector-registry");
+    // This would actually create a real Neo4jConnectionModule — just
+    // verify it doesn't throw for a known type
+    expect(() =>
+      createConnectionModule("neo4j", {
+        uri: "bolt://localhost:7687",
+        username: "neo4j",
+        password: "test",
+        authType: 1,
+      }),
+    ).not.toThrow();
+  });
+
+  it("createConnectionModule() throws for unknown type", () => {
+    const { createConnectionModule } = require("../src/connector-registry");
+    expect(() =>
+      createConnectionModule("mysql", { uri: "mysql://localhost" }),
+    ).toThrow(/Unknown connector type.*mysql/);
+  });
+});
diff --git a/connection/src/connector-registry.ts b/connection/src/connector-registry.ts
new file mode 100644
index 00000000..48017355
--- /dev/null
+++ b/connection/src/connector-registry.ts
@@ -0,0 +1,71 @@
+/**
+ * Global connector registry — singleton that auto-registers built-in
+ * connectors (Neo4j, PostgreSQL) on first import.
+ *
+ * To add a new connector:
+ *   1. Create a plugin file implementing ConnectorPlugin
+ *   2. Import and register it here
+ *
+ * External/community connectors can call registerConnector() from
+ * their own package after importing this module.
+ */
+
+import {
+  createConnectorRegistry,
+  type ConnectorPlugin,
+  type ConnectorRegistry,
+} from "./generalized/connector-plugin";
+import { neo4jPlugin } from "./neo4j/plugin";
+import { postgresPlugin } from "./postgresql/plugin";
+
+const registry: ConnectorRegistry = createConnectorRegistry();
+
+// Register built-in connectors
+registry.register(neo4jPlugin);
+registry.register(postgresPlugin);
+
+// Re-export for external use
+export { registry as connectorRegistry };
+export type { ConnectorPlugin, ConnectorRegistry };
+export { createConnectorRegistry } from "./generalized/connector-plugin";
+
+/**
+ * Convenience: register a new connector plugin.
+ */
+export function registerConnector(plugin: ConnectorPlugin): void {
+  registry.register(plugin);
+}
+
+/**
+ * Convenience: get a connector plugin by type.
+ */
+export function getConnector(type: string): ConnectorPlugin | undefined {
+  return registry.get(type);
+}
+
+/**
+ * Convenience: get all registered connector plugins.
+ */
+export function getAllConnectors(): ConnectorPlugin[] {
+  return registry.getAll();
+}
+
+/**
+ * Factory function — drop-in replacement for the old factory.ts.
+ * Creates a ConnectionModule via the registry.
+ */
+export function createConnectionModule(
+  type: string,
+  authConfig: Record<string, unknown>,
+  advancedOptions?: Record<string, unknown>,
+) {
+  const plugin = registry.get(type);
+  if (!plugin) {
+    const available = registry.getTypes().join(", ");
+    throw new Error(
+      `Unknown connector type: "${type}". Available: ${available}`,
+    );
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return plugin.createModule(authConfig as any, advancedOptions);
+}
diff --git a/connection/src/generalized/connector-plugin.ts b/connection/src/generalized/connector-plugin.ts
new file mode 100644
index 00000000..e9aa10cc
--- /dev/null
+++ b/connection/src/generalized/connector-plugin.ts
@@ -0,0 +1,120 @@
+/**
+ * Connector plugin contract.
+ *
+ * Defines everything NeoBoard needs to support a new database or service
+ * type. Implement this interface and call `registerConnector()` to make
+ * a new connector available throughout the app.
+ *
+ * Example (adding MySQL):
+ *
+ *   const mysqlPlugin: ConnectorPlugin = {
+ *     type: "mysql",
+ *     label: "MySQL",
+ *     category: "database",
+ *     queryLanguage: "sql",
+ *     supportsWrite: true,
+ *     createModule(auth, opts) { return new MysqlConnectionModule(auth, opts); },
+ *   };
+ *   registerConnector(mysqlPlugin);
+ */
+
+import type { ConnectionModule } from "./ConnectionModule";
+import type { AuthConfig } from "./interfaces";
+
+/**
+ * Connector plugin — the contract a connector must satisfy.
+ */
+export interface ConnectorPlugin {
+  /** Unique string identifier. Used in DB, URLs, and API payloads. */
+  type: string;
+
+  /** Human-readable display name shown in the connection type picker. */
+  label: string;
+
+  /** Category for grouping in the UI. */
+  category: "database" | "graph" | "api" | "file";
+
+  /**
+   * Factory: create a ConnectionModule instance from auth config.
+   * This is the only method that imports the actual database driver.
+   */
+  createModule(
+    authConfig: AuthConfig,
+    advancedOptions?: Record<string, unknown>,
+  ): ConnectionModule;
+
+  /** Does this connector produce graph data (nodes/edges)? */
+  supportsGraphData?: boolean;
+
+  /** Does this connector support write operations? */
+  supportsWrite?: boolean;
+
+  /**
+   * Query language identifier for the CodeMirror editor.
+   * Built-in: "cypher", "sql". Determines syntax highlighting.
+   */
+  queryLanguage?: string;
+
+  /**
+   * URI protocols this connector accepts (for validation).
+   * e.g. ["bolt:", "neo4j:"] or ["postgresql:"]
+   */
+  allowedProtocols?: string[];
+
+  /** Default URI placeholder shown in the connection form. */
+  uriPlaceholder?: string;
+
+  /** Default database name placeholder. */
+  databasePlaceholder?: string;
+}
+
+/**
+ * Connector registry — stores and retrieves registered connector plugins.
+ */
+export interface ConnectorRegistry {
+  register(plugin: ConnectorPlugin): void;
+  get(type: string): ConnectorPlugin | undefined;
+  has(type: string): boolean;
+  getAll(): ConnectorPlugin[];
+  getTypes(): string[];
+}
+
+/**
+ * Create a new connector registry instance.
+ */
+export function createConnectorRegistry(): ConnectorRegistry {
+  const plugins = new Map<string, ConnectorPlugin>();
+
+  return {
+    register(plugin) {
+      if (!plugin.type || plugin.type.trim() === "") {
+        throw new Error("Connector plugin: type is required");
+      }
+      if (!plugin.label || plugin.label.trim() === "") {
+        throw new Error("Connector plugin: label is required");
+      }
+      if (typeof plugin.createModule !== "function") {
+        throw new Error("Connector plugin: createModule must be a function");
+      }
+      if (plugins.has(plugin.type)) {
+        throw new Error(
+          `Connector "${plugin.type}" is already registered. ` +
+            `Call unregister first if you want to replace it.`,
+        );
+      }
+      plugins.set(plugin.type, plugin);
+    },
+    get(type) {
+      return plugins.get(type);
+    },
+    has(type) {
+      return plugins.has(type);
+    },
+    getAll() {
+      return Array.from(plugins.values());
+    },
+    getTypes() {
+      return Array.from(plugins.keys());
+    },
+  };
+}
diff --git a/connection/src/neo4j/plugin.ts b/connection/src/neo4j/plugin.ts
new file mode 100644
index 00000000..c39727fe
--- /dev/null
+++ b/connection/src/neo4j/plugin.ts
@@ -0,0 +1,36 @@
+/**
+ * Neo4j connector plugin.
+ *
+ * Registers Neo4j as a connector type. Uses the existing
+ * Neo4jConnectionModule for all connection/query operations.
+ */
+
+import type { ConnectorPlugin } from "../generalized/connector-plugin";
+import type { AuthConfig } from "../generalized/interfaces";
+import { Neo4jConnectionModule } from "./Neo4jConnectionModule";
+
+export const neo4jPlugin: ConnectorPlugin = {
+  type: "neo4j",
+  label: "Neo4j",
+  category: "graph",
+  queryLanguage: "cypher",
+  supportsGraphData: true,
+  supportsWrite: true,
+  allowedProtocols: [
+    "neo4j:",
+    "neo4j+s:",
+    "neo4j+ssc:",
+    "bolt:",
+    "bolt+s:",
+    "bolt+ssc:",
+  ],
+  uriPlaceholder: "bolt://localhost:7687",
+  databasePlaceholder: "neo4j",
+
+  createModule(
+    authConfig: AuthConfig,
+    advancedOptions?: Record<string, unknown>,
+  ) {
+    return new Neo4jConnectionModule(authConfig, advancedOptions);
+  },
+};
diff --git a/connection/src/postgresql/plugin.ts b/connection/src/postgresql/plugin.ts
new file mode 100644
index 00000000..66951159
--- /dev/null
+++ b/connection/src/postgresql/plugin.ts
@@ -0,0 +1,29 @@
+/**
+ * PostgreSQL connector plugin.
+ *
+ * Registers PostgreSQL as a connector type. Uses the existing
+ * PostgresConnectionModule for all connection/query operations.
+ */
+
+import type { ConnectorPlugin } from "../generalized/connector-plugin";
+import type { AuthConfig } from "../generalized/interfaces";
+import { PostgresConnectionModule } from "./PostgresConnectionModule";
+
+export const postgresPlugin: ConnectorPlugin = {
+  type: "postgresql",
+  label: "PostgreSQL",
+  category: "database",
+  queryLanguage: "sql",
+  supportsGraphData: false,
+  supportsWrite: true,
+  allowedProtocols: ["postgresql:", "postgres:"],
+  uriPlaceholder: "postgresql://localhost:5432/mydb",
+  databasePlaceholder: "postgres",
+
+  createModule(
+    authConfig: AuthConfig,
+    advancedOptions?: Record<string, unknown>,
+  ) {
+    return new PostgresConnectionModule(authConfig, advancedOptions);
+  },
+};

From 1d3e10db84db1d7fc09a5a6fb077f9fd0d18be2b Mon Sep 17 00:00:00 2001
From: alfredorubin96 <alfredo.rubin@neotechnology.com>
Date: Mon, 6 Apr 2026 12:51:52 +0200
Subject: [PATCH 36/36] docs: add chart plugin + connector plugin developer
 guides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two new documentation pages explaining how to extend NeoBoard:

- developer/extending/new-chart-plugin.mdx — full guide with
  defineChartPlugin() reference, PluginProps table, ECharts vs
  custom patterns, and heatmap example
- developer/extending/new-connector-plugin.mdx — ConnectorPlugin
  reference, ConnectionModule implementation guide, registry API,
  and testing patterns

Updated developer index to link plugin guides prominently.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/.astro/content-modules.mjs               |  24 ++-
 .../developer/extending/new-chart-plugin.mdx  | 197 +++++++++++++++++
 .../extending/new-connector-plugin.mdx        | 198 ++++++++++++++++++
 docs/src/content/docs/developer/index.mdx     |  17 +-
 4 files changed, 421 insertions(+), 15 deletions(-)
 create mode 100644 docs/src/content/docs/developer/extending/new-chart-plugin.mdx
 create mode 100644 docs/src/content/docs/developer/extending/new-connector-plugin.mdx

diff --git a/docs/.astro/content-modules.mjs b/docs/.astro/content-modules.mjs
index 19355ae5..22459493 100644
--- a/docs/.astro/content-modules.mjs
+++ b/docs/.astro/content-modules.mjs
@@ -1,44 +1,46 @@
 
 export default new Map([
-["src/content/docs/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/bar.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fbar.mdx&astroContentModuleFlag=true")],
-["src/content/docs/charts/form.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fform.mdx&astroContentModuleFlag=true")],
-["src/content/docs/charts/graph.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fgraph.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/iframe.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fiframe.mdx&astroContentModuleFlag=true")],
+["src/content/docs/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Findex.mdx&astroContentModuleFlag=true")],
+["src/content/docs/charts/form.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fform.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/json.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fjson.mdx&astroContentModuleFlag=true")],
-["src/content/docs/charts/line.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fline.mdx&astroContentModuleFlag=true")],
+["src/content/docs/charts/graph.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fgraph.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/map.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fmap.mdx&astroContentModuleFlag=true")],
+["src/content/docs/charts/line.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fline.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/markdown.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fmarkdown.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/param-select.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fparam-select.mdx&astroContentModuleFlag=true")],
-["src/content/docs/charts/pie.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fpie.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/single-value.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fsingle-value.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/charts/table.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Ftable.mdx&astroContentModuleFlag=true")],
+["src/content/docs/charts/pie.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcharts%2Fpie.mdx&astroContentModuleFlag=true")],
+["src/content/docs/cli/docker-setup.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcli%2Fdocker-setup.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/cli/commands.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcli%2Fcommands.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/cli/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcli%2Findex.mdx&astroContentModuleFlag=true")],
-["src/content/docs/cli/docker-setup.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcli%2Fdocker-setup.mdx&astroContentModuleFlag=true")],
-["src/content/docs/concepts/architecture.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Farchitecture.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/cli/local-setup.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcli%2Flocal-setup.mdx&astroContentModuleFlag=true")],
+["src/content/docs/concepts/architecture.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Farchitecture.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/connectors.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fconnectors.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/dashboards.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fdashboards.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/multi-tenancy.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fmulti-tenancy.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/concepts/parameters.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fparameters.mdx&astroContentModuleFlag=true")],
-["src/content/docs/concepts/widgets.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fwidgets.mdx&astroContentModuleFlag=true")],
-["src/content/docs/concepts/query-safety.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fquery-safety.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Findex.mdx&astroContentModuleFlag=true")],
+["src/content/docs/concepts/query-safety.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fquery-safety.mdx&astroContentModuleFlag=true")],
+["src/content/docs/concepts/widgets.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fwidgets.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/getting-started/configuration.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fgetting-started%2Fconfiguration.mdx&astroContentModuleFlag=true")],
-["src/content/docs/getting-started/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fgetting-started%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/getting-started/installation.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fgetting-started%2Finstallation.mdx&astroContentModuleFlag=true")],
+["src/content/docs/getting-started/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fgetting-started%2Findex.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/getting-started/quick-start.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fgetting-started%2Fquick-start.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/guides/connecting-databases.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fconnecting-databases.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/guides/first-dashboard.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Ffirst-dashboard.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/guides/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Findex.mdx&astroContentModuleFlag=true")],
-["src/content/docs/guides/managing-users.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmanaging-users.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/contributing/code-style.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fcontributing%2Fcode-style.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/contributing/pr-workflow.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fcontributing%2Fpr-workflow.mdx&astroContentModuleFlag=true")],
+["src/content/docs/guides/managing-users.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmanaging-users.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/contributing/setup.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fcontributing%2Fsetup.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/contributing/testing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fcontributing%2Ftesting.mdx&astroContentModuleFlag=true")],
+["src/content/docs/developer/extending/new-chart-plugin.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fextending%2Fnew-chart-plugin.mdx&astroContentModuleFlag=true")],
+["src/content/docs/developer/extending/new-connector-plugin.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fextending%2Fnew-connector-plugin.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/extending/new-chart-type.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fextending%2Fnew-chart-type.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/extending/new-connector.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fextending%2Fnew-connector.mdx&astroContentModuleFlag=true")],
 ["src/content/docs/developer/extending/new-parameter-type.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeveloper%2Fextending%2Fnew-parameter-type.mdx&astroContentModuleFlag=true")],
diff --git a/docs/src/content/docs/developer/extending/new-chart-plugin.mdx b/docs/src/content/docs/developer/extending/new-chart-plugin.mdx
new file mode 100644
index 00000000..a7642204
--- /dev/null
+++ b/docs/src/content/docs/developer/extending/new-chart-plugin.mdx
@@ -0,0 +1,197 @@
+---
+title: Creating a Chart Plugin
+description: Add a new chart type to NeoBoard without modifying core code.
+---
+
+NeoBoard's chart system is plugin-based. Each chart type (bar, line, pie, etc.) is a self-contained plugin that registers itself with the chart registry. You can add new chart types by creating a single plugin file.
+
+## Quick Start
+
+Create a file at `app/src/plugins/your-chart.tsx`:
+
+```tsx
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { useEChartsClick, type PluginProps } from "./utils";
+
+// Lazy-load your chart component (ECharts needs client-side only)
+const MyChart = dynamic(
+  () => import("@neoboard/components").then((m) => ({ default: m.MyChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+function MyChartPlugin({ data, settings, onChartClick }: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
+  return (
+    <MyChart
+      data={data ?? []}
+      showLegend={settings.showLegend as boolean}
+      onClick={onClick}
+    />
+  );
+}
+
+export const myChartPlugin = defineChartPlugin({
+  type: "my-chart",
+  label: "My Chart",
+  component: MyChartPlugin,
+  transform: (rows) => rows, // transform raw query rows to chart data
+  compatibleWith: ["neo4j", "postgresql"],
+  capabilities: {
+    supportsClickAction: true,
+    supportsStyling: false,
+    isECharts: true,
+    requiresQuery: true,
+  },
+  queryHint: "Return label and value columns.\nExample: RETURN name, count",
+  options: [
+    {
+      key: "showLegend",
+      label: "Show Legend",
+      type: "boolean",
+      default: true,
+      category: "Labels",
+      description: "Show the chart legend.",
+    },
+  ],
+});
+```
+
+Then register it in `app/src/plugins/index.ts`:
+
+```ts
+import { myChartPlugin } from "./my-chart";
+
+// Add to the BUILT_IN_PLUGINS array:
+const BUILT_IN_PLUGINS = [
+  // ... existing plugins
+  myChartPlugin,
+];
+```
+
+That's it. Your chart appears in the widget editor's chart type picker.
+
+## Plugin Config Reference
+
+```ts
+defineChartPlugin({
+  // Required
+  type: string,           // unique ID: "heatmap", "funnel", etc.
+  label: string,          // display name in the UI
+  component: React.FC,    // React component that renders the chart
+  transform: (data) => T, // convert raw query rows to chart's data shape
+
+  // Optional
+  transformWithMapping?: (data, mapping) => T,  // with column mapping
+  validate?: (data) => string | null,           // return error or null
+  options?: ChartOptionDef[],                   // chart options panel entries
+  queryHint?: string,                           // shown in query editor
+  compatibleWith?: ConnectorType[],             // ["neo4j", "postgresql"]
+  stylingTargets?: { value, label }[],          // enables rule-based styling
+  enrichClickEvent?: (event, row) => event,     // customize click payload
+
+  // Capabilities (all have sensible defaults)
+  capabilities?: {
+    supportsClickAction: boolean,  // default: true
+    supportsStyling: boolean,      // default: true if stylingTargets set
+    isECharts: boolean,            // default: false
+    requiresQuery: boolean,        // default: true
+  },
+});
+```
+
+## Plugin Component Props
+
+Every plugin component receives these props via `PluginProps` (import from `./utils`):
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `unknown` | Transformed query result data |
+| `settings` | `Record<string, unknown>` | User-configured chart options |
+| `onChartClick` | `(row) => void` | Raw click callback (use `useEChartsClick()` for ECharts) |
+| `stylingRules` | `StylingRule[]` | Conditional color rules |
+| `paramValues` | `Record<string, unknown>` | Current parameter values |
+| `colorScales` | `ColorScaleConfig[]` | Gradient color scales |
+| `connectionId` | `string` | Current connector ID |
+| `widgetId` | `string` | Widget identifier |
+| `resultId` | `string` | Query result cache ID |
+| `query` | `string` | Current query text |
+| `autoFit` | `boolean` | Auto-fit on resize |
+| `colorThresholds` | `string` | Legacy threshold JSON |
+
+## Chart Options
+
+Options define what users can configure in the Chart Options panel:
+
+```ts
+interface ChartOptionDef {
+  key: string;          // settings key (e.g. "showLegend")
+  label: string;        // UI label
+  type: "boolean" | "select" | "text" | "number" | "column-multi-select";
+  default: unknown;     // default value
+  category: string;     // group heading (e.g. "Layout", "Labels", "Style")
+  options?: { label: string; value: string }[];  // for "select" type
+  description?: string; // tooltip text
+}
+```
+
+## ECharts vs Custom Charts
+
+**ECharts-based charts** (bar, line, pie, gauge, etc.):
+- Use `dynamic(() => import("@neoboard/components")...)` with `ssr: false`
+- Use `useEChartsClick(onChartClick, data)` to wrap the click handler
+- Set `capabilities.isECharts: true`
+
+**Non-ECharts charts** (graph, map, table, form):
+- Import components directly (no dynamic import needed if not using browser APIs)
+- Use `onChartClick` directly (no wrapping needed)
+- Set `capabilities.isECharts: false`
+
+**Content-only widgets** (markdown, iframe):
+- Set `capabilities.requiresQuery: false`
+- `transform` returns `null`
+- No click action or styling
+
+## Example: Adding a Heatmap
+
+```tsx
+// app/src/plugins/heatmap.tsx
+import dynamic from "next/dynamic";
+import { Skeleton } from "@neoboard/components";
+import { defineChartPlugin } from "./registry";
+import { useEChartsClick, type PluginProps } from "./utils";
+
+const HeatmapChart = dynamic(
+  () => import("../components/charts/heatmap-chart").then((m) => ({ default: m.HeatmapChart })),
+  { ssr: false, loading: () => <Skeleton className="w-full h-full" /> },
+);
+
+function HeatmapPlugin({ data, settings, onChartClick }: PluginProps) {
+  const onClick = useEChartsClick(onChartClick, data);
+  return (
+    <HeatmapChart
+      data={data ?? []}
+      xField={settings.xField as string}
+      yField={settings.yField as string}
+      valueField={settings.valueField as string}
+      onClick={onClick}
+    />
+  );
+}
+
+export const heatmapPlugin = defineChartPlugin({
+  type: "heatmap",
+  label: "Heatmap",
+  component: HeatmapPlugin,
+  transform: (rows) => rows,
+  compatibleWith: ["neo4j", "postgresql"],
+  capabilities: { supportsClickAction: true, isECharts: true, requiresQuery: true, supportsStyling: false },
+  queryHint: "Return 3 columns: x, y, value.\nExample: RETURN day, hour, count",
+  options: [
+    { key: "xField", label: "X Field", type: "text", default: "", category: "Data" },
+    { key: "yField", label: "Y Field", type: "text", default: "", category: "Data" },
+    { key: "valueField", label: "Value Field", type: "text", default: "", category: "Data" },
+  ],
+});
+```
diff --git a/docs/src/content/docs/developer/extending/new-connector-plugin.mdx b/docs/src/content/docs/developer/extending/new-connector-plugin.mdx
new file mode 100644
index 00000000..bc4340d8
--- /dev/null
+++ b/docs/src/content/docs/developer/extending/new-connector-plugin.mdx
@@ -0,0 +1,198 @@
+---
+title: Creating a Connector Plugin
+description: Add a new database connector to NeoBoard without modifying core code.
+---
+
+NeoBoard's connector system is plugin-based. Each database type (Neo4j, PostgreSQL) is a self-contained plugin. You can add support for new databases by creating a connector plugin.
+
+## Quick Start
+
+Create a plugin file in the connection package:
+
+```ts
+// connection/src/my-database/plugin.ts
+import type { ConnectorPlugin } from "../generalized/connector-plugin";
+import type { AuthConfig } from "../generalized/interfaces";
+import { MyDatabaseConnectionModule } from "./MyDatabaseConnectionModule";
+
+export const myDatabasePlugin: ConnectorPlugin = {
+  type: "my-database",
+  label: "My Database",
+  category: "database",
+  queryLanguage: "sql",
+  supportsWrite: true,
+  supportsGraphData: false,
+  allowedProtocols: ["mydb:", "mydb+ssl:"],
+  uriPlaceholder: "mydb://localhost:5555/mydb",
+  databasePlaceholder: "mydb",
+
+  createModule(authConfig: AuthConfig, advancedOptions?: Record<string, unknown>) {
+    return new MyDatabaseConnectionModule(authConfig, advancedOptions);
+  },
+};
+```
+
+Then register it in `connection/src/connector-registry.ts`:
+
+```ts
+import { myDatabasePlugin } from "./my-database/plugin";
+
+// Add after the existing registrations:
+registry.register(myDatabasePlugin);
+```
+
+## Connector Plugin Reference
+
+```ts
+interface ConnectorPlugin {
+  // Required
+  type: string;           // unique ID: "mysql", "mongodb", "rest-api"
+  label: string;          // display name: "MySQL", "MongoDB"
+  category: "database" | "graph" | "api" | "file";
+  createModule(auth, opts): ConnectionModule;  // factory for the driver
+
+  // Optional
+  supportsGraphData?: boolean;    // can produce nodes/edges? (default: false)
+  supportsWrite?: boolean;        // supports INSERT/CREATE? (default: false)
+  queryLanguage?: string;         // "cypher", "sql", or custom
+  allowedProtocols?: string[];    // URI validation: ["mysql:", "mysql+ssl:"]
+  uriPlaceholder?: string;        // shown in connection form
+  databasePlaceholder?: string;   // shown in database field
+}
+```
+
+## Implementing a ConnectionModule
+
+Your connector must extend the abstract `ConnectionModule` class:
+
+```ts
+import { ConnectionModule } from "../generalized/ConnectionModule";
+import { AuthenticationModule } from "../generalized/AuthenticationModule";
+import type { ConnectionConfig, QueryCallback, QueryParams } from "../generalized/interfaces";
+
+export class MyDatabaseConnectionModule extends ConnectionModule {
+  authModule: AuthenticationModule;
+
+  constructor(authConfig: AuthConfig, advancedOptions?: Record<string, unknown>) {
+    super();
+    // Initialize your driver here
+    this.authModule = new MyDatabaseAuthModule(authConfig);
+  }
+
+  async runQuery<T>(
+    queryParams: QueryParams,
+    callbacks: QueryCallback<T>,
+    config: ConnectionConfig,
+  ): Promise<void> {
+    // Handle empty query
+    if (this.handleEmptyQuery(queryParams.query, callbacks)) return;
+
+    try {
+      // Execute the query using your driver
+      const results = await this.executeQuery(queryParams.query, queryParams.params);
+
+      // Convert results to NeoBoard's record format
+      const records = results.map(row => ({
+        // Map each column to key-value pairs
+        ...row,
+      }));
+
+      // Call the success callback
+      if (callbacks.setRecords) {
+        callbacks.setRecords(records as T);
+      }
+    } catch (error) {
+      if (callbacks.setError) {
+        callbacks.setError(error);
+      }
+    }
+  }
+
+  async checkConnection(config?: ConnectionConfig): Promise<boolean> {
+    try {
+      // Try to connect and run a simple query
+      await this.executeQuery("SELECT 1");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+## Built-in Connectors
+
+NeoBoard ships with two built-in connector plugins:
+
+### Neo4j
+- **Type:** `"neo4j"`
+- **Category:** `"graph"`
+- **Language:** Cypher
+- **Graph data:** Yes (nodes, relationships, paths)
+- **Write:** Yes (CREATE, MERGE, DELETE)
+- **Protocols:** `bolt:`, `neo4j:`, `bolt+s:`, `neo4j+s:`
+
+### PostgreSQL
+- **Type:** `"postgresql"`
+- **Category:** `"database"`
+- **Language:** SQL
+- **Graph data:** No
+- **Write:** Yes (INSERT, UPDATE, DELETE)
+- **Protocols:** `postgresql:`, `postgres:`
+
+## Registry API
+
+```ts
+import {
+  registerConnector,
+  getConnector,
+  getAllConnectors,
+  createConnectionModule,
+} from "@neoboard/connection/src/connector-registry";
+
+// Register a new connector
+registerConnector(myPlugin);
+
+// Look up a connector
+const plugin = getConnector("mysql");
+
+// List all registered connectors
+const all = getAllConnectors(); // [neo4jPlugin, postgresPlugin, ...]
+
+// Create a connection module (replaces the old factory)
+const module = createConnectionModule("neo4j", authConfig, advancedOptions);
+```
+
+## Testing Your Connector
+
+Use the existing test patterns:
+
+```ts
+// connection/__tests__/my-database/plugin.test.ts
+import { createConnectorRegistry } from "../src/generalized/connector-plugin";
+import { myDatabasePlugin } from "../src/my-database/plugin";
+
+describe("myDatabasePlugin", () => {
+  it("registers without error", () => {
+    const registry = createConnectorRegistry();
+    expect(() => registry.register(myDatabasePlugin)).not.toThrow();
+  });
+
+  it("has correct type and category", () => {
+    expect(myDatabasePlugin.type).toBe("my-database");
+    expect(myDatabasePlugin.category).toBe("database");
+  });
+
+  it("creates a connection module", () => {
+    const module = myDatabasePlugin.createModule({
+      uri: "mydb://localhost:5555/test",
+      username: "user",
+      password: "pass",
+      authType: 1,
+    });
+    expect(module).toBeDefined();
+    expect(typeof module.runQuery).toBe("function");
+    expect(typeof module.checkConnection).toBe("function");
+  });
+});
+```
diff --git a/docs/src/content/docs/developer/index.mdx b/docs/src/content/docs/developer/index.mdx
index 71783323..6e4cb6da 100644
--- a/docs/src/content/docs/developer/index.mdx
+++ b/docs/src/content/docs/developer/index.mdx
@@ -7,13 +7,22 @@ import { LinkCard, CardGrid } from '@astrojs/starlight/components';
 
 This section covers how to extend NeoBoard and contribute to the project.
 
-## Extending NeoBoard
+## Plugin System
 
-Step-by-step guides for adding new functionality:
+NeoBoard uses a plugin architecture. Add new chart types or database connectors without modifying core code:
 
 <CardGrid>
-  <LinkCard title="New Chart Type" href="/developer/extending/new-chart-type" />
-  <LinkCard title="New Connector" href="/developer/extending/new-connector" />
+  <LinkCard title="Chart Plugin" description="Add a new chart type (heatmap, funnel, etc.)" href="/developer/extending/new-chart-plugin" />
+  <LinkCard title="Connector Plugin" description="Add a new database (MySQL, MongoDB, etc.)" href="/developer/extending/new-connector-plugin" />
+</CardGrid>
+
+## Legacy Extending Guides
+
+Older guides (before the plugin system):
+
+<CardGrid>
+  <LinkCard title="New Chart Type (legacy)" href="/developer/extending/new-chart-type" />
+  <LinkCard title="New Connector (legacy)" href="/developer/extending/new-connector" />
   <LinkCard title="New Parameter Type" href="/developer/extending/new-parameter-type" />
   <LinkCard title="New Widget Type" href="/developer/extending/new-widget-type" />
 </CardGrid>