feat(r/flexible_board): allow panel positions to be autogenerated (#716)

## Which problem is this PR solving?

- changes internals of position on flexible board panel to handle
computed values better.
- This allows the API to compute height, width and coordinates (x,y)
- Without this change, we cannot solve the problem of auto assigning
panels to specific grid spots

## How to verify that this has the expected result
- create a flexible board with panels without positions
- create a flexible board with panels with positions

fixes
#692

Author: roncodingenthusiast

client/board.go

@@ -44,6 +44,10 @@ type Board struct {
 	// Defaults to "classic".
 	BoardType BoardType `json:"type,omitempty"`
 
+	// Layout generation controls how the board layout is generated.
+	// Defaults to "manual".
+	LayoutGeneration LayoutGeneration `json:"layout_generation,omitempty"`
+
 	// Board panels are the individual panels that make up a board. Each panel can
 	// be a query or an SLO panel. The panels are laid out in a grid.
 	Panels []BoardPanel `json:"panels,omitempty"`
@@ -80,6 +84,10 @@ type BoardPanel struct {
 	SLOPanel   *BoardSLOPanel   `json:"slo_panel,omitempty"`
 }
 
+func (b *BoardPanel) IsBlank() bool {
+	return b.PanelPosition.X == 0 && b.PanelPosition.Y == 0 && b.PanelPosition.Height == 0 && b.PanelPosition.Width == 0
+}
+
 type BoardPanelType string
 
 const (
@@ -128,6 +136,13 @@ const (
 	BoardTypeFlexible BoardType = "flexible"
 )
 
+type LayoutGeneration string
+
+const (
+	LayoutGenerationManual LayoutGeneration = "manual"
+	LayoutGenerationAuto   LayoutGeneration = "auto"
+)
+
 // BoardStyle determines how a Board should be displayed within the Honeycomb UI.
 type BoardStyle string
 

client/board_test.go

@@ -248,6 +248,55 @@ func TestFlexibleBoards(t *testing.T) {
 		assert.Equal(t, data, flexibleBoard)
 	})
 
+	t.Run("Create flexible board with auto layout generation", func(t *testing.T) {
+		data := &client.Board{
+			Name:             test.RandomStringWithPrefix("test.", 8),
+			BoardType:        "flexible",
+			Description:      "A board with some panels",
+			LayoutGeneration: client.LayoutGenerationAuto,
+			Panels: []client.BoardPanel{
+				{
+					PanelType: client.BoardPanelTypeQuery,
+					QueryPanel: &client.BoardQueryPanel{
+						QueryID:           *query.ID,
+						QueryAnnotationID: queryAnnotation.ID,
+						Style:             client.BoardQueryStyleGraph,
+					},
+				},
+				{
+					PanelType: client.BoardPanelTypeSLO,
+					SLOPanel: &client.BoardSLOPanel{
+						SLOID: slo.ID,
+					},
+				},
+			},
+		}
+		flexibleBoard, err = c.Boards.Create(ctx, data)
+		require.NoError(t, err)
+		assert.NotNil(t, flexibleBoard.ID)
+
+		// copy ID before asserting equality
+		data.ID = flexibleBoard.ID
+
+		// ensure the board URL got populated
+		assert.NotEmpty(t, flexibleBoard.Links.BoardURL)
+		data.Links.BoardURL = flexibleBoard.Links.BoardURL
+
+		for i, panel := range flexibleBoard.Panels {
+			assert.Equal(t, data.Panels[i].PanelType, panel.PanelType)
+			assert.Equal(t, data.Panels[i].QueryPanel, panel.QueryPanel)
+			assert.Equal(t, data.Panels[i].SLOPanel, panel.SLOPanel)
+
+			// since positions are auto generated, we can't assert their exact values
+			// but we can assert that they are not empty
+			assert.NotEmpty(t, panel.PanelPosition)
+			assert.GreaterOrEqual(t, panel.PanelPosition.X, 0)
+			assert.GreaterOrEqual(t, panel.PanelPosition.Y, 0)
+			assert.Positive(t, panel.PanelPosition.Height)
+			assert.Positive(t, panel.PanelPosition.Width)
+		}
+	})
+
 	t.Run("Create flexible board with tags", func(t *testing.T) {
 		data := &client.Board{
 			Name:        test.RandomStringWithPrefix("test.", 8),

docs/resources/board.md

@@ -1,10 +1,10 @@
 # Resource: honeycombio_board
 
-Creates a classic board. Classic boards are deprecated, use [honeycombio_flexible_board](./flexible_board.md) resource instead. For more information about boards, check out [Create Custom Boards](https://docs.honeycomb.io/observe/boards).
+Creates a legacy board. Legacy boards are deprecated, use [honeycombio_flexible_board](./flexible_board.md) resource instead. For more information about boards, check out [Create Custom Boards](https://docs.honeycomb.io/observe/boards).
 
 ## Example Usage
 
-### Simple Classic Board
+### Simple Legacy Board
 
 ```hcl
 data "honeycombio_query_specification" "query" {
@@ -35,7 +35,7 @@ resource "honeycombio_board" "board" {
 }
 ```
 
-### Classic Board with a Service Level Objective (SLO) and an annotated query
+### Legacy Board with a Service Level Objective (SLO) and an annotated query
 
 ```hcl
 data "honeycombio_query_specification" "latency_by_userid" {
@@ -116,7 +116,6 @@ Each board configuration may have zero or more `query` blocks, which accept the
 - `graph_settings` - (Optional) A map of boolean toggles to manages the settings for this query's graph on the board.
   If a value is unspecified, it is assumed to be false.
   Currently supported toggles are:
-
     - `hide_markers`
     - `log_scale`
     - `omit_missing_values`

docs/resources/flexible_board.md

@@ -90,13 +90,6 @@ resource "honeycombio_flexible_board" "overview" {
   panel {
     type = "query"
 
-    position {
-      x_coordinate = 0
-      y_coordinate = 0
-      width        = 6
-      height       = 6
-    }
-
     query_panel {
       query_id            = honeycombio_query.latency_by_userid.id
       query_annotation_id = honeycombio_query_annotation.latency_by_userid.id
@@ -139,10 +132,10 @@ Each board configuration may have zero or more `panel` blocks which accept the f
 
 Each `position` configuration accepts the following arguments:
 
-- `x_coordinate` - (Optional) The x-axis origin point for placing the panel within the layout.
-- `y_coordinate` - (Optional) The y-axis origin point for placing the panel within the layout.
-- `width` - (Optional) The width of the panel in honeycomb UI columns. Defaults to 6 for queries and 3 for slos. Maximum value is 12.
-- `height` - (Optional) The height of the panel in rows. Defaults to 4.
+- `x_coordinate` - (Optional) The x-axis origin point for placing the panel within the layout. Must be provided with `y_coordinate`.
+- `y_coordinate` - (Optional) The y-axis origin point for placing the panel within the layout. Must be provided with `x_coordinate`.
+- `width` - (Optional) The width of the panel in honeycomb UI columns. Automatically calculated when not provided. Maximum value is 12.
+- `height` - (Optional) The height of the panel in rows. Automatically calculated when not provided.
 
 Each `slo_panel` configuration accepts the following arguments:
 

example/flexible_board/main.tf

@@ -111,5 +111,11 @@ resource "honeycombio_flexible_board" "overview" {
     slo_panel {
       slo_id = honeycombio_slo.slo.id
     }
+    position {
+      x_coordinate = 6
+      y_coordinate = 0
+      width        = 6
+      height       = 6
+    }
   }
 }

example/board/main.tf renamed to example/legacy_board/main.tf

@@ -0,0 +1,103 @@
+package validation
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-framework-validators/helpers/validatordiag"
+	"github.com/hashicorp/terraform-plugin-framework/schema/validator"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+var _ validator.List = panelPositionsConsistencyValidator{}
+
+// panelPositionsConsistencyValidator validates that either all panels have positions or none of them do.
+type panelPositionsConsistencyValidator struct{}
+
+func (v panelPositionsConsistencyValidator) Description(_ context.Context) string {
+	return "either all panels must have positions or none of them should have positions"
+}
+
+func (v panelPositionsConsistencyValidator) MarkdownDescription(ctx context.Context) string {
+	return v.Description(ctx)
+}
+
+func (v panelPositionsConsistencyValidator) ValidateList(ctx context.Context, request validator.ListRequest, response *validator.ListResponse) {
+	if request.ConfigValue.IsNull() || request.ConfigValue.IsUnknown() {
+		return
+	}
+
+	elements := request.ConfigValue.Elements()
+	if len(elements) == 0 {
+		return
+	}
+
+	var hasPositionCount int
+	var noPositionCount int
+
+	for _, element := range elements {
+		if element.IsNull() || element.IsUnknown() {
+			continue
+		}
+
+		panelObj, ok := element.(types.Object)
+		if !ok {
+			continue
+		}
+
+		attrs := panelObj.Attributes()
+		position, exists := attrs["position"]
+		if !exists {
+			continue
+		}
+
+		// Check if position is set (not null and not unknown)
+		if position.IsNull() || position.IsUnknown() {
+			noPositionCount++
+		} else {
+			// Check if position object has any actual values set
+			positionObj, ok := position.(types.Object)
+			if !ok {
+				noPositionCount++
+				continue
+			}
+
+			positionAttrs := positionObj.Attributes()
+			hasAnyCoordinate := false
+
+			// Check if any coordinate is set
+			for _, coordName := range []string{"x_coordinate", "y_coordinate"} {
+				if coord, exists := positionAttrs[coordName]; exists {
+					if !coord.IsNull() && !coord.IsUnknown() {
+						hasAnyCoordinate = true
+						break
+					}
+				}
+			}
+
+			if hasAnyCoordinate {
+				hasPositionCount++
+			} else {
+				noPositionCount++
+			}
+		}
+	}
+
+	// If we have both panels with positions and panels without positions, that's invalid
+	if hasPositionCount > 0 && noPositionCount > 0 {
+		response.Diagnostics.Append(
+			validatordiag.InvalidAttributeValueDiagnostic(
+				request.Path,
+				v.Description(ctx),
+				"Found panels with positions and panels without positions. All panels must have consistent position configuration.",
+			),
+		)
+	}
+}
+
+// RequireConsistentPanelPositions returns a ListValidator which ensures that either all panels
+// have positions or none of them do.
+//
+// Null (unconfigured) and unknown (known after apply) values are skipped.
+func RequireConsistentPanelPositions() validator.List {
+	return panelPositionsConsistencyValidator{}
+}