feat: add plugin schema for area chart panel

docs/api/openapi.yml

@@ -2646,6 +2646,54 @@ components:
         repeatVariable:
           type: string
       type: object
+    DashboardtypesAreaChartAppearance:
+      properties:
+        fillMode:
+          $ref: '#/components/schemas/DashboardtypesAreaFillMode'
+        fillOpacity:
+          $ref: '#/components/schemas/DashboardtypesFillOpacity'
+        lineInterpolation:
+          $ref: '#/components/schemas/DashboardtypesLineInterpolation'
+        lineStyle:
+          $ref: '#/components/schemas/DashboardtypesLineStyle'
+        showPoints:
+          type: boolean
+        spanGaps:
+          $ref: '#/components/schemas/DashboardtypesSpanGaps'
+      type: object
+    DashboardtypesAreaChartPanelSpec:
+      properties:
+        axes:
+          $ref: '#/components/schemas/DashboardtypesAxes'
+        chartAppearance:
+          $ref: '#/components/schemas/DashboardtypesAreaChartAppearance'
+        formatting:
+          $ref: '#/components/schemas/DashboardtypesPanelFormatting'
+        legend:
+          $ref: '#/components/schemas/DashboardtypesLegend'
+        thresholds:
+          items:
+            $ref: '#/components/schemas/DashboardtypesThresholdWithLabel'
+          nullable: true
+          type: array
+        visualization:
+          $ref: '#/components/schemas/DashboardtypesAreaChartVisualization'
+      type: object
+    DashboardtypesAreaChartVisualization:
+      properties:
+        fillSpans:
+          type: boolean
+        stack:
+          $ref: '#/components/schemas/DashboardtypesStackMode'
+        timePreference:
+          $ref: '#/components/schemas/DashboardtypesTimePreference'
+      type: object
+    DashboardtypesAreaFillMode:
+      enum:
+      - solid
+      - gradient
+      - none
+      type: string
     DashboardtypesAxes:
       properties:
         isLogScale:
@@ -2877,6 +2925,11 @@ components:
       - gradient
       - none
       type: string
+    DashboardtypesFillOpacity:
+      maximum: 1
+      minimum: 0
+      nullable: true
+      type: number
     DashboardtypesGettableDashboardV2:
       properties:
         createdAt:
@@ -3294,6 +3347,7 @@ components:
     DashboardtypesPanelPlugin:
       discriminator:
         mapping:
+          signoz/AreaChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec'
           signoz/BarChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec'
           signoz/HistogramPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec'
           signoz/ListPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec'
@@ -3305,6 +3359,7 @@ components:
       oneOf:
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec'
+      - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec'
@@ -3315,12 +3370,25 @@ components:
       enum:
       - signoz/TimeSeriesPanel
       - signoz/BarChartPanel
+      - signoz/AreaChartPanel
       - signoz/NumberPanel
       - signoz/PieChartPanel
       - signoz/TablePanel
       - signoz/HistogramPanel
       - signoz/ListPanel
       type: string
+    DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec:
+      properties:
+        kind:
+          enum:
+          - signoz/AreaChartPanel
+          type: string
+        spec:
+          $ref: '#/components/schemas/DashboardtypesAreaChartPanelSpec'
+      required:
+      - kind
+      - spec
+      type: object
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec:
       properties:
         kind:
@@ -3639,6 +3707,12 @@ components:
             are connected.
           type: boolean
       type: object
+    DashboardtypesStackMode:
+      enum:
+      - none
+      - normal
+      - percent
+      type: string
     DashboardtypesStorableDashboardData:
       additionalProperties: {}
       type: object

pkg/types/dashboardtypes/perses_dashboard_test.go

@@ -1274,6 +1274,264 @@ func TestTimeSeriesPanelDefaults(t *testing.T) {
 	}
 }
 
+func TestAreaChartPanelDefaults(t *testing.T) {
+	data := []byte(`{
+		"variables": [],
+		"panels": {
+			"p1": {
+				"kind": "Panel",
+				"spec": {
+					"links": [],
+					"plugin": {
+						"kind": "signoz/AreaChartPanel",
+						"spec": {}
+					},
+					"queries": [{"kind": "time_series", "spec": {"plugin": {"kind": "signoz/PromQLQuery", "spec": {"name": "A", "query": "up"}}}}]
+				}
+			}
+		},
+		"links": [],
+		"layouts": []
+	}`)
+	d, err := unmarshalDashboard(data)
+	require.NoError(t, err, "unmarshal and validate failed")
+
+	require.IsType(t, &AreaChartPanelSpec{}, d.Panels["p1"].Spec.Plugin.Spec)
+	spec := d.Panels["p1"].Spec.Plugin.Spec.(*AreaChartPanelSpec)
+
+	assert.Equal(t, "solid", spec.ChartAppearance.FillMode.ValueOrDefault(), "area fillMode defaults to solid, where the TimeSeries FillMode defaults to none")
+	assert.Nil(t, spec.ChartAppearance.FillOpacity, "an omitted fillOpacity stays nil so the renderer applies the kind default")
+	assert.Equal(t, "none", spec.Visualization.Stack.ValueOrDefault(), "expected Stack default none")
+	assert.Equal(t, "2", spec.Formatting.DecimalPrecision.ValueOrDefault(), "expected DecimalPrecision default 2")
+	assert.Equal(t, "spline", spec.ChartAppearance.LineInterpolation.ValueOrDefault(), "expected LineInterpolation default spline")
+	assert.Equal(t, "solid", spec.ChartAppearance.LineStyle.ValueOrDefault(), "expected LineStyle default solid")
+	assert.Equal(t, "global_time", spec.Visualization.TimePreference.ValueOrDefault(), "expected TimePreference default global_time")
+	assert.Equal(t, "bottom", spec.Legend.Position.ValueOrDefault(), "expected LegendPosition default bottom")
+	assert.Equal(t, "list", spec.Legend.Mode.ValueOrDefault(), "expected LegendMode default list")
+
+	output, err := json.Marshal(d)
+	require.NoError(t, err, "marshal dashboard failed")
+	outputStr := string(output)
+	for field, want := range map[string]string{
+		"fillMode":    `"solid"`,
+		"stack":       `"none"`,
+		"fillOpacity": `null`,
+	} {
+		assert.Contains(t, outputStr, `"`+field+`":`+want, "expected stored/response JSON to contain %s:%s", field, want)
+	}
+}
+
+func TestAreaChartPanelRoundTrip(t *testing.T) {
+	data := []byte(`{
+		"variables": [],
+		"panels": {
+			"p1": {
+				"kind": "Panel",
+				"spec": {
+					"links": [],
+					"plugin": {
+						"kind": "signoz/AreaChartPanel",
+						"spec": {
+							"visualization": {"timePreference": "global_time", "fillSpans": false, "stack": "percent"},
+							"chartAppearance": {"fillMode": "gradient", "fillOpacity": 0.4}
+						}
+					},
+					"queries": [{"kind": "time_series", "spec": {"plugin": {"kind": "signoz/PromQLQuery", "spec": {"name": "A", "query": "up"}}}}]
+				}
+			}
+		},
+		"links": [],
+		"layouts": []
+	}`)
+	d, err := unmarshalDashboard(data)
+	require.NoError(t, err, "unmarshal and validate failed")
+
+	require.IsType(t, &AreaChartPanelSpec{}, d.Panels["p1"].Spec.Plugin.Spec)
+	spec := d.Panels["p1"].Spec.Plugin.Spec.(*AreaChartPanelSpec)
+
+	assert.Equal(t, "percent", spec.Visualization.Stack.ValueOrDefault(), "expected stack percent")
+	assert.Equal(t, "gradient", spec.ChartAppearance.FillMode.ValueOrDefault(), "expected fillMode gradient")
+
+	output, err := json.Marshal(d)
+	require.NoError(t, err, "marshal dashboard failed")
+	assert.Contains(t, string(output), `"stack":"percent"`, "expected stack in stored/response JSON")
+	assert.Contains(t, string(output), `"fillMode":"gradient"`, "expected fillMode in stored/response JSON")
+}
+
+func TestAreaChartPanelFillOpacity(t *testing.T) {
+	tests := []struct {
+		scenario                 string
+		chartAppearance          string
+		expectedFillOpacitySet   bool
+		expectedFillOpacityValue FillOpacity
+		expectedMarshalledJSON   string
+	}{
+		{
+			scenario:                 "zero is a set value, not an absent one",
+			chartAppearance:          `{"fillOpacity": 0}`,
+			expectedFillOpacitySet:   true,
+			expectedFillOpacityValue: 0,
+			expectedMarshalledJSON:   `"fillOpacity":0`,
+		},
+		{
+			scenario:                 "fully opaque upper bound",
+			chartAppearance:          `{"fillOpacity": 1}`,
+			expectedFillOpacitySet:   true,
+			expectedFillOpacityValue: 1,
+			expectedMarshalledJSON:   `"fillOpacity":1`,
+		},
+		{
+			scenario:                 "typical fractional value",
+			chartAppearance:          `{"fillOpacity": 0.4}`,
+			expectedFillOpacitySet:   true,
+			expectedFillOpacityValue: 0.4,
+			expectedMarshalledJSON:   `"fillOpacity":0.4`,
+		},
+		{
+			scenario:                 "precision beyond one decimal place survives",
+			chartAppearance:          `{"fillOpacity": 0.125}`,
+			expectedFillOpacitySet:   true,
+			expectedFillOpacityValue: 0.125,
+			expectedMarshalledJSON:   `"fillOpacity":0.125`,
+		},
+		{
+			scenario:               "omitted field stays nil so the renderer applies the kind default",
+			chartAppearance:        `{}`,
+			expectedFillOpacitySet: false,
+			expectedMarshalledJSON: `"fillOpacity":null`,
+		},
+		{
+			scenario:               "explicit null stays nil rather than decoding as zero",
+			chartAppearance:        `{"fillOpacity": null}`,
+			expectedFillOpacitySet: false,
+			expectedMarshalledJSON: `"fillOpacity":null`,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.scenario, func(t *testing.T) {
+			data := []byte(`{
+				"variables": [],
+				"panels": {
+					"p1": {
+						"kind": "Panel",
+						"spec": {
+							"links": [],
+							"plugin": {"kind": "signoz/AreaChartPanel", "spec": {"chartAppearance": ` + test.chartAppearance + `}},
+							"queries": [{"kind": "time_series", "spec": {"plugin": {"kind": "signoz/PromQLQuery", "spec": {"name": "A", "query": "up"}}}}]
+						}
+					}
+				},
+				"links": [],
+				"layouts": []
+			}`)
+			d, err := unmarshalDashboard(data)
+			require.NoError(t, err, "unmarshal and validate failed")
+
+			require.IsType(t, &AreaChartPanelSpec{}, d.Panels["p1"].Spec.Plugin.Spec)
+			spec := d.Panels["p1"].Spec.Plugin.Spec.(*AreaChartPanelSpec)
+
+			if !test.expectedFillOpacitySet {
+				assert.Nil(t, spec.ChartAppearance.FillOpacity, "expected fillOpacity to stay unset")
+			} else {
+				require.NotNil(t, spec.ChartAppearance.FillOpacity, "expected fillOpacity to decode as a set value")
+				assert.Equal(t, test.expectedFillOpacityValue, *spec.ChartAppearance.FillOpacity, "unexpected decoded fillOpacity")
+			}
+
+			output, err := json.Marshal(d)
+			require.NoError(t, err, "marshal dashboard failed")
+			assert.Contains(t, string(output), test.expectedMarshalledJSON, "unexpected fillOpacity in stored/response JSON")
+		})
+	}
+}
+
+func TestInvalidateAreaChartPanelSpecValues(t *testing.T) {
+	tests := []struct {
+		scenario               string
+		panelKind              string
+		panelSpec              string
+		expectedErrorSubstring string
+	}{
+		{
+			scenario:               "unknown stack mode",
+			panelKind:              "signoz/AreaChartPanel",
+			panelSpec:              `{"visualization": {"stack": "stacked"}}`,
+			expectedErrorSubstring: "stack mode",
+		},
+		{
+			scenario:               "unknown area fill mode",
+			panelKind:              "signoz/AreaChartPanel",
+			panelSpec:              `{"chartAppearance": {"fillMode": "striped"}}`,
+			expectedErrorSubstring: "fill mode",
+		},
+		{
+			scenario:               "fill opacity on a 0-100 scale",
+			panelKind:              "signoz/AreaChartPanel",
+			panelSpec:              `{"chartAppearance": {"fillOpacity": 40}}`,
+			expectedErrorSubstring: "invalid fillOpacity 40: must be between 0 and 1",
+		},
+		{
+			scenario:               "negative fill opacity",
+			panelKind:              "signoz/AreaChartPanel",
+			panelSpec:              `{"chartAppearance": {"fillOpacity": -0.5}}`,
+			expectedErrorSubstring: "invalid fillOpacity -0.5: must be between 0 and 1",
+		},
+		{
+			scenario:               "non-numeric fill opacity",
+			panelKind:              "signoz/AreaChartPanel",
+			panelSpec:              `{"chartAppearance": {"fillOpacity": "0.4"}}`,
+			expectedErrorSubstring: "cannot unmarshal string",
+		},
+		{
+			scenario:               "stack on a time series panel",
+			panelKind:              "signoz/TimeSeriesPanel",
+			panelSpec:              `{"visualization": {"stack": "normal"}}`,
+			expectedErrorSubstring: `unknown field`,
+		},
+		{
+			scenario:               "fill opacity on a time series panel",
+			panelKind:              "signoz/TimeSeriesPanel",
+			panelSpec:              `{"chartAppearance": {"fillOpacity": 0.4}}`,
+			expectedErrorSubstring: `unknown field`,
+		},
+		{
+			scenario:               "stacked bar chart on an area panel",
+			panelKind:              "signoz/AreaChartPanel",
+			panelSpec:              `{"visualization": {"stackedBarChart": true}}`,
+			expectedErrorSubstring: `unknown field`,
+		},
+		{
+			scenario:               "stack on a bar chart panel",
+			panelKind:              "signoz/BarChartPanel",
+			panelSpec:              `{"visualization": {"stack": "percent"}}`,
+			expectedErrorSubstring: `unknown field`,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.scenario, func(t *testing.T) {
+			data := []byte(`{
+				"variables": [],
+				"panels": {
+					"p1": {
+						"kind": "Panel",
+						"spec": {
+							"links": [],
+							"plugin": {"kind": "` + test.panelKind + `", "spec": ` + test.panelSpec + `},
+							"queries": [{"kind": "time_series", "spec": {"plugin": {"kind": "signoz/PromQLQuery", "spec": {"name": "A", "query": "up"}}}}]
+						}
+					}
+				},
+				"links": [],
+				"layouts": []
+			}`)
+			_, err := unmarshalDashboard(data)
+			require.Error(t, err, "expected the spec to be rejected")
+			assert.Contains(t, err.Error(), test.expectedErrorSubstring, "unexpected error message: %s", err.Error())
+		})
+	}
+}
+
 func TestNumberPanelDefaults(t *testing.T) {
 	data := []byte(`{
 		"variables": [],

pkg/types/dashboardtypes/perses_plugin_wrappers.go

@@ -30,6 +30,7 @@ func (PanelPlugin) PrepareJSONSchema(s *jsonschema.Schema) error {
 	return markDiscriminator(s, "kind", map[string]string{
 		string(PanelKindTimeSeries): schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec"),
 		string(PanelKindBarChart):   schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec"),
+		string(PanelKindAreaChart):  schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec"),
 		string(PanelKindNumber):     schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec"),
 		string(PanelKindPieChart):   schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec"),
 		string(PanelKindTable):      schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec"),
@@ -60,6 +61,7 @@ func (PanelPlugin) JSONSchemaOneOf() []any {
 	return []any{
 		PanelPluginVariant[TimeSeriesPanelSpec]{Kind: string(PanelKindTimeSeries)},
 		PanelPluginVariant[BarChartPanelSpec]{Kind: string(PanelKindBarChart)},
+		PanelPluginVariant[AreaChartPanelSpec]{Kind: string(PanelKindAreaChart)},
 		PanelPluginVariant[NumberPanelSpec]{Kind: string(PanelKindNumber)},
 		PanelPluginVariant[PieChartPanelSpec]{Kind: string(PanelKindPieChart)},
 		PanelPluginVariant[TablePanelSpec]{Kind: string(PanelKindTable)},
@@ -223,6 +225,7 @@ var (
 	panelPluginSpecs = map[PanelPluginKind]func() any{
 		PanelKindTimeSeries: func() any { return new(TimeSeriesPanelSpec) },
 		PanelKindBarChart:   func() any { return new(BarChartPanelSpec) },
+		PanelKindAreaChart:  func() any { return new(AreaChartPanelSpec) },
 		PanelKindNumber:     func() any { return new(NumberPanelSpec) },
 		PanelKindPieChart:   func() any { return new(PieChartPanelSpec) },
 		PanelKindTable:      func() any { return new(TablePanelSpec) },
@@ -245,6 +248,7 @@ var (
 	allowedQueryKinds = map[PanelPluginKind][]QueryPluginKind{
 		PanelKindTimeSeries: {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
 		PanelKindBarChart:   {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindAreaChart:  {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
 		PanelKindNumber:     {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
 		PanelKindHistogram:  {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
 		PanelKindPieChart:   {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindClickHouseSQL},

pkg/types/dashboardtypes/perses_public_dashboard.go

@@ -183,7 +183,8 @@ func (d *DashboardV2) GetPanelQuery(startTime, endTime uint64, panelKey string)
 		return nil, err
 	}
 
-	// fillGaps lives on the panel visualization; only timeseries and bar chart carry it.
+	// fillGaps lives on the panel visualization; only timeseries, bar chart and
+	// area chart carry it.
 	fillGaps := false
 	switch panelSpec := panel.Spec.Plugin.Spec.(type) {
 	case *TimeSeriesPanelSpec:
@@ -194,6 +195,10 @@ func (d *DashboardV2) GetPanelQuery(startTime, endTime uint64, panelKey string)
 		if panelSpec != nil {
 			fillGaps = panelSpec.Visualization.FillSpans
 		}
+	case *AreaChartPanelSpec:
+		if panelSpec != nil {
+			fillGaps = panelSpec.Visualization.FillSpans
+		}
 	}
 
 	return &qb.QueryRangeRequest{

pkg/types/dashboardtypes/perses_signoz_plugins.go

@@ -168,6 +168,7 @@ type PanelPluginKind string
 const (
 	PanelKindTimeSeries PanelPluginKind = "signoz/TimeSeriesPanel"
 	PanelKindBarChart   PanelPluginKind = "signoz/BarChartPanel"
+	PanelKindAreaChart  PanelPluginKind = "signoz/AreaChartPanel"
 	PanelKindNumber     PanelPluginKind = "signoz/NumberPanel"
 	PanelKindPieChart   PanelPluginKind = "signoz/PieChartPanel"
 	PanelKindTable      PanelPluginKind = "signoz/TablePanel"
@@ -176,7 +177,7 @@ const (
 )
 
 func (PanelPluginKind) Enum() []any {
-	return []any{PanelKindTimeSeries, PanelKindBarChart, PanelKindNumber, PanelKindPieChart, PanelKindTable, PanelKindHistogram, PanelKindList}
+	return []any{PanelKindTimeSeries, PanelKindBarChart, PanelKindAreaChart, PanelKindNumber, PanelKindPieChart, PanelKindTable, PanelKindHistogram, PanelKindList}
 }
 
 type TimeSeriesPanelSpec struct {
@@ -204,6 +205,30 @@ type BarChartPanelSpec struct {
 	Thresholds    []ThresholdWithLabel  `json:"thresholds" validate:"dive"`
 }
 
+type AreaChartPanelSpec struct {
+	Visualization   AreaChartVisualization `json:"visualization"`
+	Formatting      PanelFormatting        `json:"formatting"`
+	ChartAppearance AreaChartAppearance    `json:"chartAppearance"`
+	Axes            Axes                   `json:"axes"`
+	Legend          Legend                 `json:"legend"`
+	Thresholds      []ThresholdWithLabel   `json:"thresholds" validate:"dive"`
+}
+
+// AreaChartAppearance repeats the line-drawing fields rather than embedding
+// TimeSeriesChartAppearance: both carry a `fillMode` under different enums, and
+// a duplicated json tag across an embed boundary is resolved by depth, which the
+// schema reflector does not model.
+type AreaChartAppearance struct {
+	LineInterpolation LineInterpolation `json:"lineInterpolation"`
+	ShowPoints        bool              `json:"showPoints"`
+	LineStyle         LineStyle         `json:"lineStyle"`
+	FillMode          AreaFillMode      `json:"fillMode"`
+	// FillOpacity is a pointer so an omitted field resolves to the kind default at
+	// render time; a plain value would make the Go zero value a transparent fill.
+	FillOpacity *FillOpacity `json:"fillOpacity"`
+	SpanGaps    SpanGaps     `json:"spanGaps"`
+}
+
 type NumberPanelSpec struct {
 	Visualization BasicVisualization    `json:"visualization"`
 	Formatting    PanelFormatting       `json:"formatting"`
@@ -262,6 +287,12 @@ type BarChartVisualization struct {
 	StackedBarChart bool `json:"stackedBarChart"`
 }
 
+type AreaChartVisualization struct {
+	BasicVisualization
+	FillSpans bool      `json:"fillSpans"`
+	Stack     StackMode `json:"stack"`
+}
+
 type PanelFormatting struct {
 	Unit             string          `json:"unit"`
 	DecimalPrecision PrecisionOption `json:"decimalPrecision"`
@@ -622,6 +653,112 @@ func (fm *FillMode) UnmarshalJSON(data []byte) error {
 	}
 }
 
+// AreaFillMode is separate from FillMode so area panels can default to `solid`.
+// An area panel that omits the field would otherwise render as a bare line, and
+// flipping FillMode's default would change how existing TimeSeries panels render.
+type AreaFillMode struct{ valuer.String }
+
+var (
+	AreaFillModeSolid    = AreaFillMode{valuer.NewString("solid")} // default
+	AreaFillModeGradient = AreaFillMode{valuer.NewString("gradient")}
+	// AreaFillModeNone lets an area panel degrade to a line without the save API
+	// rejecting it, so an Area -> TimeSeries -> Area round trip keeps its config.
+	AreaFillModeNone = AreaFillMode{valuer.NewString("none")}
+)
+
+func (AreaFillMode) Enum() []any {
+	return []any{AreaFillModeSolid, AreaFillModeGradient, AreaFillModeNone}
+}
+
+func (fm AreaFillMode) ValueOrDefault() string {
+	if fm.IsZero() {
+		return AreaFillModeSolid.StringValue()
+	}
+	return fm.StringValue()
+}
+
+func (fm AreaFillMode) MarshalJSON() ([]byte, error) {
+	return json.Marshal(fm.ValueOrDefault())
+}
+
+func (fm *AreaFillMode) UnmarshalJSON(data []byte) error {
+	var v string
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid fill mode: must be a string, one of `solid`, `gradient`, or `none`")
+	}
+	val := AreaFillMode{valuer.NewString(v)}
+	switch val {
+	case AreaFillModeSolid, AreaFillModeGradient, AreaFillModeNone:
+		*fm = val
+		return nil
+	default:
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid fill mode %q: must be `solid`, `gradient`, or `none`", v)
+	}
+}
+
+// StackMode is area-only. Bar stacking stays on BarChartVisualization.StackedBarChart,
+// so `percent` is not reachable from a bar panel.
+type StackMode struct{ valuer.String }
+
+var (
+	StackModeNone    = StackMode{valuer.NewString("none")} // default
+	StackModeNormal  = StackMode{valuer.NewString("normal")}
+	StackModePercent = StackMode{valuer.NewString("percent")}
+)
+
+func (StackMode) Enum() []any {
+	return []any{StackModeNone, StackModeNormal, StackModePercent}
+}
+
+func (sm StackMode) ValueOrDefault() string {
+	if sm.IsZero() {
+		return StackModeNone.StringValue()
+	}
+	return sm.StringValue()
+}
+
+func (sm StackMode) MarshalJSON() ([]byte, error) {
+	return json.Marshal(sm.ValueOrDefault())
+}
+
+func (sm *StackMode) UnmarshalJSON(data []byte) error {
+	var v string
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid stack mode: must be a string, one of `none`, `normal`, or `percent`")
+	}
+	val := StackMode{valuer.NewString(v)}
+	switch val {
+	case StackModeNone, StackModeNormal, StackModePercent:
+		*sm = val
+		return nil
+	default:
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid stack mode %q: must be `none`, `normal`, or `percent`", v)
+	}
+}
+
+// FillOpacity is the alpha of an area fill, in 0–1 because that is what the
+// chart layer consumes directly. Unlike the enums in this section it has no
+// ValueOrDefault: 0 is a legitimate value, so the kind default lives at render
+// time behind a nil pointer.
+type FillOpacity float64
+
+func (FillOpacity) PrepareJSONSchema(s *jsonschema.Schema) error {
+	s.WithMinimum(0).WithMaximum(1)
+	return nil
+}
+
+func (o *FillOpacity) UnmarshalJSON(data []byte) error {
+	var v float64
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid fillOpacity: must be a number between 0 and 1")
+	}
+	if v < 0 || v > 1 {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid fillOpacity %v: must be between 0 and 1", v)
+	}
+	*o = FillOpacity(v)
+	return nil
+}
+
 type SpanGaps struct {
 	FillOnlyBelow bool   `json:"fillOnlyBelow" description:"Controls whether lines connect across null values. When false (default), all gaps are connected. When true, only gaps smaller than fillLessThan are connected."`
 	FillLessThan  string `json:"fillLessThan" description:"The maximum gap size to connect when fillOnlyBelow is true. Gaps larger than this duration are left disconnected."`

pkg/types/dashboardtypes/perses_v1_to_v2.go

@@ -14,6 +14,11 @@ import (
 // (transition.dashboardMigrateV5). Pre-v5 builder queries will produce
 // invalid v2 envelopes — run the v4→v5 migration first.
 //
+// The v1 input shape is closed: nothing writes v1 dashboards any more, so these
+// files only ever convert what v1 could already express. Panel kinds and spec
+// fields added to v2 from here on need no converter entry — change these files
+// only when a v2 type edit breaks the build.
+//
 // The conversion is split across sibling files by concern:
 //   - perses_v1_to_v2_tags.go      tags
 //   - perses_v1_to_v2_panels.go    widgets → panels (+ panel field mappers)